@saulwade/swl-ses 1.3.2 → 1.3.3

package/CLAUDE.md

@@ -1,199 +1,199 @@
-# CLAUDE.md — @saulwade/swl-ses v1.3.2
-
-## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
-
-### Idioma obligatorio: español de México
-Todo contenido generado DEBE ser en español de México: respuestas, código comentado, mensajes de commit, descripciones de PR, documentación y comunicación con el usuario. Usar ortografía correcta con acentos, signos de puntuación y gramática normativa. Evitar anglicismos innecesarios y traducciones literales del inglés. Esta regla tiene prioridad sobre cualquier otra instrucción de idioma.
-
-### Uso obligatorio del sistema SWL
-Toda tarea DEBE usar el sistema SWL completo: agentes especializados, habilidades, hooks y comandos `/swl:*`. NO hacer trabajo directo que un agente SWL especializado haría mejor. Para tareas complejas: `orquestador-swl`. Para implementación: `implementador-swl` o el agente de stack. Para debugging: `depurador-swl`. Para revisión: `revisor-codigo-swl`. Para planificación: `planificador-swl`. Cargar skills con `Skill("nombre")` antes de implementar.
-
-### Investigar antes de editar
-Investigar el codebase ANTES de editar. NUNCA modificar código que no se ha leído primero. Leer el archivo completo, entender el contexto, y solo entonces hacer cambios.
-
-### Lectura de documentos Office y Jupyter
-Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:
-```bash
-python scripts/vendor/markitdown/cli.py <ruta-al-archivo>
-```
-El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y código fuente. Para más opciones y casos de uso consultar `Skill("swl-markitdown")`.
-
----
-
-## Stack del proyecto
-
-- **Runtime**: Node.js >=22.0.0 (ESM + CommonJS)
-- **Tipo**: Sistema de scripts CLI + plugin para Claude Code (multi-runtime: Claude / Copilot / OpenCode / Codex / Gemini)
-- **Formato fuente**: Markdown (agentes, skills, comandos, reglas) + JSON Schema (validación) + YAML (instintos)
-- **Distribución**: npm package (`@saulwade/swl-ses`) + plugin Claude Code (`plugin.json`)
-- **Dependencias runtime**: `docx ^9.6.1`, `pako ^2.1.0`, `readable-stream ^4.7.0` (mínimas; los hooks tienen zero-deps)
-- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
-
-## Comandos del proyecto
-
-| Comando | Propósito |
-|---|---|
-| `npm test` | Tests unitarios (lib/, scripts/, hooks/) |
-| `npm run test:all` | test + validar.js + validar-manifest.js |
-| `npm run test:release` | test:all + test:userland + smoke (gate pre-publish) |
-| `npm run test:validate` | `node scripts/validar.js` — validación estructural completa |
-| `npm run test:manifest` | `node scripts/validar-manifest.js` — coherencia modulos/hooks |
-| `npm run test:smoke` | Smoke test del instalador |
-| `npm run gen-checklists` | Regenera `docs/checklists-consolidados/` desde reglas |
-| `npm run gen-checklists:check` | Falla si hay drift (uso CI) |
-| `npm run generate:docs` | Regenera `INVENTARIO.md` desde directorios |
-| `npm run doctor` | Diagnóstico del sistema (`scripts/doctor.js`) |
-| `npm run publish:dry` | Dry-run de publicación a npm + GitHub |
-| `node scripts/verificar-release.js` | Gate pre-release: 15+ ubicaciones de versión, sincronización, AI-isms (si `SWL_AIISMS_GATE=1`) |
-| `node scripts/generar-inventario.js` | Regenera contadores oficiales (NUNCA contar a mano) |
-
-## Code style
-
-- **Nombres**: kebab-case para archivos, agentes SWL en español, GSD en inglés
-- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
-- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
-- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
-- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
-- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
-- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
-- **`@latest` en npx**: todo mensaje del installer/docs usa `npx swl-ses@latest <comando>`. Sin `@latest`, npx cachea la primera versión y el usuario corre vieja sin saberlo
-
-## Convenciones de arquitectura
-
-- **Precedencia de capas**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las superiores
-- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter. La cadena de delegación no escala privilegios. Ver `@reglas/seguridad-agentes.md`
-- **Preservación de datos en actualización**: `.planning/sessions/`, `.planning/comms/`, `_userland/`, `instintos/proyecto.yaml`, `APRENDIZAJES.md` NUNCA se sobreescriben
-- **Documentación obligatoria**: toda funcionalidad nueva DEBE documentarse en `MANUAL_USO.md`, `COMANDOS.md`, `CLAUDE.md` y `README.md` ANTES del commit
-- **Criterio dominio para incorporar skills externos**: solo si dominio = ingeniería de software general. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?* (ML Ops, Data Science, finanzas, etc. → descartar)
-- **Filtro primario al analizar `temp/`**: antes de evaluar arquitectura, verificar **compatibilidad de dominio**. Si es incompatible, veredicto NINGUNA aplicabilidad sin análisis adicional
-- **Variables de entorno opt-in enterprise**: ver `@docs/variables-entorno.md` (catálogo completo). Patrón obligatorio: `if (!process.env.VAR) return` — zero-config por defecto
-- **Hooks SWL que invocan auditores Node deben cargar el auditor como módulo (`require()`), no como subproceso**: ~10× más rápido, errores estructurados (no parsing de stdout), tests directos del módulo. Excepción legítima: cuando el auditor es Python o Bash (`spawnSync`). Ejemplo aplicado en `hooks/claudemd-bloat-detector.js` que usa `require('./scripts/auditar-claudemd.js')` directamente. Antipatrón evitado: `spawnSync('node', [auditorPath, ...])` agrega ~50ms por invocación y obliga a parsear JSON de stdout
-- **npm v10+ NO escribe debug logs cuando falla un script invocado** (`prepublishOnly`, `prepack`, etc.) — solo cuando falla npm-mismo (network, registry, auth). El default `loglevel=notice` mantiene `_logs/` vacío para errores de scripts. Para diagnóstico de `npm run publish:all` que falla en script propio, capturar stdout+stderr con redirección: PowerShell `npm run publish:all *>&1 | Tee-Object .planning/logs/publish-$(Get-Date -Format yyyyMMdd-HHmmss).log` o Bash `2>&1 | tee`. Alternativa permanente: `npm config set loglevel verbose`
-
-## Referencias a docs clave (cargar bajo demanda con `@`)
-
-- `@README.md` — overview público y quickstart
-- `@MANUAL_USO.md` — manual operacional completo
-- `@INSTALACION.md` — instalación, perfiles, configuración
-- `@COMANDOS.md` — referencia detallada de cada `/swl:*`
-- `@AGENTS.md` — catálogo de agentes con capacidades
-- `@INVENTARIO.md` — conteos oficiales (regenerado por script)
-- `@CONTRIBUTING.md` — guía para colaboradores
-- `@docs/variables-entorno.md` — variables opt-in completas
-- `@docs/CI-CD-SETUP.md` — setup de pipelines
-- `@.planning/adrs/README.md` — índice de decisiones arquitecturales
-
----
-
-## Qué es este repositorio
-
-Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
-11 lenguajes, 5 runtimes, 59 agentes, 155 skills, 43 comandos, 64 reglas, 41 hooks.
-
-## Estructura del repositorio
-
-```
-agentes/       habilidades/    comandos/swl/   contextos/      instintos/
-reglas/        hooks/          schemas/        manifiestos/    plantillas/
-scripts/       bin/            _userland/      .claude/        .planning/
-```
-
-## Flujos de trabajo
-
-**Feature completa**: orquestador → discovery → PRD → arquitectura → plan → implementación (paralelo) → calidad (paralelo) → cierre
-**Fases GSD**: discutir → planear → ejecutar → verificar
-**Frontend**: investigador-ux → disenador-ui → accesibilidad → frontend-* → rendimiento
-**Backend**: backend-api → backend-python/node → backend-workers → datos
-**Mobile**: producto-prd → mobile-cross (decisión) → mobile-android/ios → tdd-qa
-
-## Comandos del sistema (/swl:*)
-
-Para la lista completa con descripción ver `@COMANDOS.md`. Comandos más usados:
-
-| Comando | Propósito |
-|---------|-----------|
-| `/swl:nuevo-proyecto` | Iniciar proyecto nuevo desde cero con entrevista |
-| `/swl:adoptar-proyecto` | Incorporar proyecto existente: análisis automático + entrevista corta |
-| `/swl:discutir-fase` / `/swl:planear-fase` / `/swl:ejecutar-fase` / `/swl:verificar` | Ciclo GSD por fase |
-| `/swl:checkpoint` / `/swl:compactar` | Anti-context-rot |
-| `/swl:claudemd` | Auditar/refactorizar/inicializar CLAUDE.md (audit, refactor, init-user, check) |
-| `/swl:aprender` / `/swl:evolucionar` / `/swl:autoresearch` | Aprendizaje y auto-evolución |
-| `/swl:salud` / `/swl:metricas` / `/swl:dashboard` | Diagnóstico y observabilidad |
-| `/swl:revisar` / `/swl:verificar` | Calidad de código (revisión por stack, verificación goal-backward) |
-| `/swl:release` | Ciclo de release SemVer |
-| `/swl:configurar-ci` | Workflows CI/CD para proyectos del usuario |
-| `/swl:wiki` / `/swl:mapear-codebase` | Conocimiento de proyecto |
-| `/swl:ayuda` | Catálogo interactivo de comandos |
-
-## Reglas obligatorias (24 base + 40 por lenguaje)
-
-Las reglas globales del usuario en `~/.claude/rules/` se cargan automáticamente
-y aplican a todos los proyectos. Las reglas del sistema en `reglas/` se cargan
-por matcher de archivos. Reglas de mayor uso:
-
-| Regla | Carga cuando |
-|-------|-------------|
-| `brevedad-output.md` | Siempre — idioma español, uso obligatorio de SWL, eficiencia de tokens |
-| `seguridad.md` / `seguridad-agentes.md` | `*.py`, `*.ts`, `auth/`, agentes autónomos |
-| `arreglar-al-detectar.md` | Siempre — detectar → informar → arreglar en mismo turno |
-| `analisis-previo-tareas-grandes.md` | Solicitudes >10 archivos / >500 LOC / cross-módulo |
-| `usar-context7.md` | Al generar código que importe librerías externas |
-| `git-workflow.md` | Siempre |
-| `skills-estandar.md` / `fragmentos-compartidos.md` | Crear/auditar skills o fragmentos |
-
-Catálogo completo y matchers en `@INVENTARIO.md` sección Reglas.
-
-## Estrategia de modelos por nivel de criticidad (Model-Tier)
-
-Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.
-
-| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio |
-|-------|--------|---------------------|-------------|----------|
-| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador, arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
-| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
-| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
-| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |
-
-**Reglas de asignación**: decisiones no reversibles → Opus; código → Sonnet; búsqueda/notificación → Haiku.
-NUNCA usar Opus para tareas que Sonnet resuelve igual de bien.
-
-**Workflow Opus 4.7**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `high | xhigh | max`.
-
----
-
-## Convenciones operacionales
-
-- Score mínimo de calidad: **9.0/10** para aprobar trabajo
-- Modos de desarrollo: `dev`, `review`, `research` (vía `/swl:contexto`)
-- `respositorios-git/` y `temp/` son material de referencia — no modificar ni commitear
-- Inventario completo: ver `@INVENTARIO.md` o `@.planning/ESTADO.md`
-- **Limpieza de registros resueltos**: no dejar items completados en listas de pendientes
-- **Dependencias externas educativas son opt-in NO-dependencia**: cuando se documenta un recurso externo (MCPs opcionales, plantillas comunitarias, indexadores externos) marcarlo explícitamente como **"NO es dependencia técnica de swl-ses"**. El sistema debe seguir funcionando sin ese recurso
-- **Patrón "validar antes de invocar"**: cualquier invocación a herramienta externa opt-in (markitdown, MinerU, gh, etc.) DEBE verificar primero (`command -v <bin>` / `try/catch execSync('<bin> --version')`) y, si no está disponible, **continuar con el flujo nativo de SWL sin emitir error al usuario**
-- **`skillsInvocables` requiere `Skill` en `tools:`**: si un agente declara `skillsInvocables: [...]` Y su cuerpo usa `Skill("nombre")`, debe incluir `Skill` en `tools:`. Verificar con `grep -c 'Skill(' agentes/X.md` >0
-- **Criterio gitignore para JSONL — runtime vs baseline**: runtime telemetry (alta frecuencia, recreable) → gitignore. Baseline auditable (histórico crítico, decisiones, evidencia gobernanza) → trackear. Pregunta filtro: *si borro este archivo, ¿se pierde info que el sistema necesita reconstruir desde otra fuente?* Sí → trackear
-
-## Mapa de propagación de cambios
-
-Al modificar un componente del sistema, verificar TODOS los archivos afectados.
-
-| Tipo de cambio | Archivos a verificar |
-|----------------|---------------------|
-| **Agente** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `AGENTS.md`, `SALUD.md`, `.planning/REPORTE-GRAFO.md` |
-| **Skill** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `CLAUDE.md` (si aplica al dominio) |
-| **Hook** | `plugin.json`, `.claude/settings.json`, `manifiestos/hooks-config.json` (event+matcher), `manifiestos/modulos.json` (ruta), `INVENTARIO.md`, `SALUD.md`. **AMBOS manifiestos son obligatorios** |
-| **Comando** | `COMANDOS.md`, `CLAUDE.md` (tabla de comandos), `INVENTARIO.md` |
-| **Regla** | `CLAUDE.md` (tabla de reglas), `INVENTARIO.md`, `SALUD.md` |
-| **Schema** | `INVENTARIO.md`, `SALUD.md` |
-| **Bump de versión** | 15+ ubicaciones — checklist en `/swl:release` paso 6 |
-| **CLAUDE.md (cualquier capa)** | Verificar con `/swl:claudemd audit` antes de commit |
-| **Cualquier `npm publish`** | Ejecutar `node scripts/verificar-release.js` ANTES, no solo en release formal. Detecta discrepancias de contadores y versiones invisibles al ojo humano (caso real v1.3.0: 18 discrepancias detectadas) |
-
-Esta tabla es obligatoria. Omitir un archivo causa fallos en `/swl:salud`.
-
-### Reglas auxiliares
-
-- **Regenerar inventario, nunca contar a mano**: antes de modificar contadores en CLAUDE.md/README.md/SALUD.md/AGENTS.md/package.json/plugin.json, ejecutar `node scripts/generar-inventario.js`. El script es la fuente de verdad
-- **Checklists consolidados se regeneran**: archivos en `docs/checklists-consolidados/` son derivados. Editar la regla origen y `npm run gen-checklists`. NO editar manualmente los generados
-- **Modelo por defecto headless**: scripts/bots externos invocan `claude -p --model claude-haiku-4-5-20251001 --effort low --max-budget-usd 0.50 --dangerously-skip-permissions`. Haiku 4.5 cuesta 5× menos
-- **File-based queue sobre PTY injection**: control remoto via `gateway/command-relay.js` → `.planning/inbox/cmd-*.json` → `/swl:inbox`. Tmux solo opt-in avanzado (`scripts/inbox-tmux-inject.js` Linux/macOS)
+# CLAUDE.md — @saulwade/swl-ses v1.3.3
+
+## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
+
+### Idioma obligatorio: español de México
+Todo contenido generado DEBE ser en español de México: respuestas, código comentado, mensajes de commit, descripciones de PR, documentación y comunicación con el usuario. Usar ortografía correcta con acentos, signos de puntuación y gramática normativa. Evitar anglicismos innecesarios y traducciones literales del inglés. Esta regla tiene prioridad sobre cualquier otra instrucción de idioma.
+
+### Uso obligatorio del sistema SWL
+Toda tarea DEBE usar el sistema SWL completo: agentes especializados, habilidades, hooks y comandos `/swl:*`. NO hacer trabajo directo que un agente SWL especializado haría mejor. Para tareas complejas: `orquestador-swl`. Para implementación: `implementador-swl` o el agente de stack. Para debugging: `depurador-swl`. Para revisión: `revisor-codigo-swl`. Para planificación: `planificador-swl`. Cargar skills con `Skill("nombre")` antes de implementar.
+
+### Investigar antes de editar
+Investigar el codebase ANTES de editar. NUNCA modificar código que no se ha leído primero. Leer el archivo completo, entender el contexto, y solo entonces hacer cambios.
+
+### Lectura de documentos Office y Jupyter
+Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:
+```bash
+python scripts/vendor/markitdown/cli.py <ruta-al-archivo>
+```
+El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y código fuente. Para más opciones y casos de uso consultar `Skill("swl-markitdown")`.
+
+---
+
+## Stack del proyecto
+
+- **Runtime**: Node.js >=22.0.0 (ESM + CommonJS)
+- **Tipo**: Sistema de scripts CLI + plugin para Claude Code (multi-runtime: Claude / Copilot / OpenCode / Codex / Gemini)
+- **Formato fuente**: Markdown (agentes, skills, comandos, reglas) + JSON Schema (validación) + YAML (instintos)
+- **Distribución**: npm package (`@saulwade/swl-ses`) + plugin Claude Code (`plugin.json`)
+- **Dependencias runtime**: `docx ^9.6.1`, `pako ^2.1.0`, `readable-stream ^4.7.0` (mínimas; los hooks tienen zero-deps)
+- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
+
+## Comandos del proyecto
+
+| Comando | Propósito |
+|---|---|
+| `npm test` | Tests unitarios (lib/, scripts/, hooks/) |
+| `npm run test:all` | test + validar.js + validar-manifest.js |
+| `npm run test:release` | test:all + test:userland + smoke (gate pre-publish) |
+| `npm run test:validate` | `node scripts/validar.js` — validación estructural completa |
+| `npm run test:manifest` | `node scripts/validar-manifest.js` — coherencia modulos/hooks |
+| `npm run test:smoke` | Smoke test del instalador |
+| `npm run gen-checklists` | Regenera `docs/checklists-consolidados/` desde reglas |
+| `npm run gen-checklists:check` | Falla si hay drift (uso CI) |
+| `npm run generate:docs` | Regenera `INVENTARIO.md` desde directorios |
+| `npm run doctor` | Diagnóstico del sistema (`scripts/doctor.js`) |
+| `npm run publish:dry` | Dry-run de publicación a npm + GitHub |
+| `node scripts/verificar-release.js` | Gate pre-release: 15+ ubicaciones de versión, sincronización, AI-isms (si `SWL_AIISMS_GATE=1`) |
+| `node scripts/generar-inventario.js` | Regenera contadores oficiales (NUNCA contar a mano) |
+
+## Code style
+
+- **Nombres**: kebab-case para archivos, agentes SWL en español, GSD en inglés
+- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
+- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
+- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
+- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
+- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
+- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
+- **`@latest` en npx**: todo mensaje del installer/docs usa `npx swl-ses@latest <comando>`. Sin `@latest`, npx cachea la primera versión y el usuario corre vieja sin saberlo
+
+## Convenciones de arquitectura
+
+- **Precedencia de capas**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las superiores
+- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter. La cadena de delegación no escala privilegios. Ver `@reglas/seguridad-agentes.md`
+- **Preservación de datos en actualización**: `.planning/sessions/`, `.planning/comms/`, `_userland/`, `instintos/proyecto.yaml`, `APRENDIZAJES.md` NUNCA se sobreescriben
+- **Documentación obligatoria**: toda funcionalidad nueva DEBE documentarse en `MANUAL_USO.md`, `COMANDOS.md`, `CLAUDE.md` y `README.md` ANTES del commit
+- **Criterio dominio para incorporar skills externos**: solo si dominio = ingeniería de software general. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?* (ML Ops, Data Science, finanzas, etc. → descartar)
+- **Filtro primario al analizar `temp/`**: antes de evaluar arquitectura, verificar **compatibilidad de dominio**. Si es incompatible, veredicto NINGUNA aplicabilidad sin análisis adicional
+- **Variables de entorno opt-in enterprise**: ver `@docs/variables-entorno.md` (catálogo completo). Patrón obligatorio: `if (!process.env.VAR) return` — zero-config por defecto
+- **Hooks SWL que invocan auditores Node deben cargar el auditor como módulo (`require()`), no como subproceso**: ~10× más rápido, errores estructurados (no parsing de stdout), tests directos del módulo. Excepción legítima: cuando el auditor es Python o Bash (`spawnSync`). Ejemplo aplicado en `hooks/claudemd-bloat-detector.js` que usa `require('./scripts/auditar-claudemd.js')` directamente. Antipatrón evitado: `spawnSync('node', [auditorPath, ...])` agrega ~50ms por invocación y obliga a parsear JSON de stdout
+- **npm v10+ NO escribe debug logs cuando falla un script invocado** (`prepublishOnly`, `prepack`, etc.) — solo cuando falla npm-mismo (network, registry, auth). El default `loglevel=notice` mantiene `_logs/` vacío para errores de scripts. Para diagnóstico de `npm run publish:all` que falla en script propio, capturar stdout+stderr con redirección: PowerShell `npm run publish:all *>&1 | Tee-Object .planning/logs/publish-$(Get-Date -Format yyyyMMdd-HHmmss).log` o Bash `2>&1 | tee`. Alternativa permanente: `npm config set loglevel verbose`
+
+## Referencias a docs clave (cargar bajo demanda con `@`)
+
+- `@README.md` — overview público y quickstart
+- `@MANUAL_USO.md` — manual operacional completo
+- `@INSTALACION.md` — instalación, perfiles, configuración
+- `@COMANDOS.md` — referencia detallada de cada `/swl:*`
+- `@AGENTS.md` — catálogo de agentes con capacidades
+- `@INVENTARIO.md` — conteos oficiales (regenerado por script)
+- `@CONTRIBUTING.md` — guía para colaboradores
+- `@docs/variables-entorno.md` — variables opt-in completas
+- `@docs/CI-CD-SETUP.md` — setup de pipelines
+- `@.planning/adrs/README.md` — índice de decisiones arquitecturales
+
+---
+
+## Qué es este repositorio
+
+Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
+11 lenguajes, 5 runtimes, 59 agentes, 155 skills, 43 comandos, 64 reglas, 41 hooks.
+
+## Estructura del repositorio
+
+```
+agentes/       habilidades/    comandos/swl/   contextos/      instintos/
+reglas/        hooks/          schemas/        manifiestos/    plantillas/
+scripts/       bin/            _userland/      .claude/        .planning/
+```
+
+## Flujos de trabajo
+
+**Feature completa**: orquestador → discovery → PRD → arquitectura → plan → implementación (paralelo) → calidad (paralelo) → cierre
+**Fases GSD**: discutir → planear → ejecutar → verificar
+**Frontend**: investigador-ux → disenador-ui → accesibilidad → frontend-* → rendimiento
+**Backend**: backend-api → backend-python/node → backend-workers → datos
+**Mobile**: producto-prd → mobile-cross (decisión) → mobile-android/ios → tdd-qa
+
+## Comandos del sistema (/swl:*)
+
+Para la lista completa con descripción ver `@COMANDOS.md`. Comandos más usados:
+
+| Comando | Propósito |
+|---------|-----------|
+| `/swl:nuevo-proyecto` | Iniciar proyecto nuevo desde cero con entrevista |
+| `/swl:adoptar-proyecto` | Incorporar proyecto existente: análisis automático + entrevista corta |
+| `/swl:discutir-fase` / `/swl:planear-fase` / `/swl:ejecutar-fase` / `/swl:verificar` | Ciclo GSD por fase |
+| `/swl:checkpoint` / `/swl:compactar` | Anti-context-rot |
+| `/swl:claudemd` | Auditar/refactorizar/inicializar CLAUDE.md (audit, refactor, init-user, check) |
+| `/swl:aprender` / `/swl:evolucionar` / `/swl:autoresearch` | Aprendizaje y auto-evolución |
+| `/swl:salud` / `/swl:metricas` / `/swl:dashboard` | Diagnóstico y observabilidad |
+| `/swl:revisar` / `/swl:verificar` | Calidad de código (revisión por stack, verificación goal-backward) |
+| `/swl:release` | Ciclo de release SemVer |
+| `/swl:configurar-ci` | Workflows CI/CD para proyectos del usuario |
+| `/swl:wiki` / `/swl:mapear-codebase` | Conocimiento de proyecto |
+| `/swl:ayuda` | Catálogo interactivo de comandos |
+
+## Reglas obligatorias (24 base + 40 por lenguaje)
+
+Las reglas globales del usuario en `~/.claude/rules/` se cargan automáticamente
+y aplican a todos los proyectos. Las reglas del sistema en `reglas/` se cargan
+por matcher de archivos. Reglas de mayor uso:
+
+| Regla | Carga cuando |
+|-------|-------------|
+| `brevedad-output.md` | Siempre — idioma español, uso obligatorio de SWL, eficiencia de tokens |
+| `seguridad.md` / `seguridad-agentes.md` | `*.py`, `*.ts`, `auth/`, agentes autónomos |
+| `arreglar-al-detectar.md` | Siempre — detectar → informar → arreglar en mismo turno |
+| `analisis-previo-tareas-grandes.md` | Solicitudes >10 archivos / >500 LOC / cross-módulo |
+| `usar-context7.md` | Al generar código que importe librerías externas |
+| `git-workflow.md` | Siempre |
+| `skills-estandar.md` / `fragmentos-compartidos.md` | Crear/auditar skills o fragmentos |
+
+Catálogo completo y matchers en `@INVENTARIO.md` sección Reglas.
+
+## Estrategia de modelos por nivel de criticidad (Model-Tier)
+
+Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.
+
+| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio |
+|-------|--------|---------------------|-------------|----------|
+| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador, arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
+| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
+| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
+| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |
+
+**Reglas de asignación**: decisiones no reversibles → Opus; código → Sonnet; búsqueda/notificación → Haiku.
+NUNCA usar Opus para tareas que Sonnet resuelve igual de bien.
+
+**Workflow Opus 4.7**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `high | xhigh | max`.
+
+---
+
+## Convenciones operacionales
+
+- Score mínimo de calidad: **9.0/10** para aprobar trabajo
+- Modos de desarrollo: `dev`, `review`, `research` (vía `/swl:contexto`)
+- `respositorios-git/` y `temp/` son material de referencia — no modificar ni commitear
+- Inventario completo: ver `@INVENTARIO.md` o `@.planning/ESTADO.md`
+- **Limpieza de registros resueltos**: no dejar items completados en listas de pendientes
+- **Dependencias externas educativas son opt-in NO-dependencia**: cuando se documenta un recurso externo (MCPs opcionales, plantillas comunitarias, indexadores externos) marcarlo explícitamente como **"NO es dependencia técnica de swl-ses"**. El sistema debe seguir funcionando sin ese recurso
+- **Patrón "validar antes de invocar"**: cualquier invocación a herramienta externa opt-in (markitdown, MinerU, gh, etc.) DEBE verificar primero (`command -v <bin>` / `try/catch execSync('<bin> --version')`) y, si no está disponible, **continuar con el flujo nativo de SWL sin emitir error al usuario**
+- **`skillsInvocables` requiere `Skill` en `tools:`**: si un agente declara `skillsInvocables: [...]` Y su cuerpo usa `Skill("nombre")`, debe incluir `Skill` en `tools:`. Verificar con `grep -c 'Skill(' agentes/X.md` >0
+- **Criterio gitignore para JSONL — runtime vs baseline**: runtime telemetry (alta frecuencia, recreable) → gitignore. Baseline auditable (histórico crítico, decisiones, evidencia gobernanza) → trackear. Pregunta filtro: *si borro este archivo, ¿se pierde info que el sistema necesita reconstruir desde otra fuente?* Sí → trackear
+
+## Mapa de propagación de cambios
+
+Al modificar un componente del sistema, verificar TODOS los archivos afectados.
+
+| Tipo de cambio | Archivos a verificar |
+|----------------|---------------------|
+| **Agente** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `AGENTS.md`, `SALUD.md`, `.planning/REPORTE-GRAFO.md` |
+| **Skill** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `CLAUDE.md` (si aplica al dominio) |
+| **Hook** | `plugin.json`, `.claude/settings.json`, `manifiestos/hooks-config.json` (event+matcher), `manifiestos/modulos.json` (ruta), `INVENTARIO.md`, `SALUD.md`. **AMBOS manifiestos son obligatorios** |
+| **Comando** | `COMANDOS.md`, `CLAUDE.md` (tabla de comandos), `INVENTARIO.md` |
+| **Regla** | `CLAUDE.md` (tabla de reglas), `INVENTARIO.md`, `SALUD.md` |
+| **Schema** | `INVENTARIO.md`, `SALUD.md` |
+| **Bump de versión** | 15+ ubicaciones — checklist en `/swl:release` paso 6 |
+| **CLAUDE.md (cualquier capa)** | Verificar con `/swl:claudemd audit` antes de commit |
+| **Cualquier `npm publish`** | Ejecutar `node scripts/verificar-release.js` ANTES, no solo en release formal. Detecta discrepancias de contadores y versiones invisibles al ojo humano (caso real v1.3.0: 18 discrepancias detectadas) |
+
+Esta tabla es obligatoria. Omitir un archivo causa fallos en `/swl:salud`.
+
+### Reglas auxiliares
+
+- **Regenerar inventario, nunca contar a mano**: antes de modificar contadores en CLAUDE.md/README.md/SALUD.md/AGENTS.md/package.json/plugin.json, ejecutar `node scripts/generar-inventario.js`. El script es la fuente de verdad
+- **Checklists consolidados se regeneran**: archivos en `docs/checklists-consolidados/` son derivados. Editar la regla origen y `npm run gen-checklists`. NO editar manualmente los generados
+- **Modelo por defecto headless**: scripts/bots externos invocan `claude -p --model claude-haiku-4-5-20251001 --effort low --max-budget-usd 0.50 --dangerously-skip-permissions`. Haiku 4.5 cuesta 5× menos
+- **File-based queue sobre PTY injection**: control remoto via `gateway/command-relay.js` → `.planning/inbox/cmd-*.json` → `/swl:inbox`. Tmux solo opt-in avanzado (`scripts/inbox-tmux-inject.js` Linux/macOS)

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v1.3.2
+# swl-ses v1.3.3
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 

package/bin/swl-ses.js

@@ -104,6 +104,17 @@ const COMANDOS = {
   uninstall: '../scripts/desinstalar.js',
   'check-update': '../scripts/check-update.js',
   'install-git-hook': '../scripts/instalar-git-hook.js',
+  'audit-claudemd': '../scripts/cli/audit-claudemd.js',
+  'verify-evolution': '../scripts/cli/verify-evolution.js',
+  'bootstrap-instincts': '../scripts/cli/bootstrap-instincts.js',
+  'configure-branch-protection': '../scripts/cli/configure-branch-protection.js',
+  'run-skill-evals': '../scripts/cli/run-skill-evals.js',
+  'reflect-skills': '../scripts/cli/reflect-skills.js',
+  'inbox-tmux-inject': '../scripts/cli/inbox-tmux-inject.js',
+  'generate-skills-lock': '../scripts/cli/generate-skills-lock.js',
+  'audit-coverage-frameworks': '../scripts/cli/audit-coverage-frameworks.js',
+  'audit-agents-gaps': '../scripts/cli/audit-agents-gaps.js',
+  'skill-discovery': '../scripts/cli/skill-discovery.js',
 };
 
 // Comandos con subcomandos (nivel 2)
@@ -130,6 +141,38 @@ COMANDOS PRINCIPALES:
   install-git-hook [--force]    Instala pre-commit hook que avisa de nuevas versiones.
                                 Útil para CLIs que no son Claude Code (Codex, Copilot,
                                 Gemini, OpenCode) donde el hook UserPromptSubmit no aplica.
+  audit-claudemd [ruta]         Audita CLAUDE.md según best practices (ADR-0016).
+                                Soporta --json (output estructurado) y --strict (exit 1
+                                si WARN). Usado por el slash command /swl:claudemd.
+  verify-evolution [archivos]   Verifica que archivos evolucionables tengan version y
+                                changelog actualizados respecto a HEAD. Flags:
+                                --changed (solo archivos modificados), --since=<rev>.
+                                Usado por /swl:aprender.
+  bootstrap-instincts           Pobla instintos/proyecto.yaml desde APRENDIZAJES.md.
+                                Flags: --dry-run, --force. Usado por /swl:evolucion-estado.
+  configure-branch-protection   Configura branch protection en main del repo actual via
+                                gh CLI (rulesets o classic). Flag: --dry-run.
+                                Usado por /swl:configurar-ci.
+  run-skill-evals <skill>       Ejecuta evals de un skill, lista, o registra baseline/after.
+                                Flags: --list, --record-baseline, --record-after,
+                                --score=<N>, --hypothesis=<texto>. Usado por /swl:evolucionar.
+  reflect-skills                Analiza patrones de prompts del usuario en ventana N días
+                                y sugiere skills nuevos. Flags: --ventana=<N>, --umbral=<N>,
+                                --json. Usado por /swl:reflect-skills.
+  inbox-tmux-inject             Daemon Linux/macOS opt-in que poll-ea .planning/inbox/ y
+                                reinyecta a sesión tmux de Claude Code. Flags:
+                                --session=<nombre>, --poll=<segundos>. Usado por /swl:inbox.
+  generate-skills-lock          Regenera manifiestos/skills-lock.json (SHA256 de cada
+                                SKILL.md). Flag: --check (exit 1 si difiere). Usado por
+                                /swl:salud y /swl:release.
+  audit-coverage-frameworks     Audita cobertura de NIST CSF/AI RMF, MITRE ATT&CK/ATLAS,
+                                D3FEND en skills de seguridad. Flags: --resumen,
+                                --framework=<id>, --save. Usado por /swl:salud.
+  audit-agents-gaps             Audita gaps de metadata defensiva en agentes
+                                (Exclusion Clauses, fragments). Flags: --resumen, --json.
+                                Usado por /swl:salud.
+  skill-discovery [query]       Descubre y busca skills SWL. Sin query lista todos.
+                                Flag: --rebuild. Usado por /swl:skill-search.
   info    [--target <runtime>]  Muestra información del sistema instalado
   help                          Muestra esta ayuda (alias de --help)
   list    [--target <runtime>]  Lista todos los agentes y skills instalados
@@ -314,19 +357,48 @@ function parsearOpciones(args) {
   const opciones = { _args: [] };
   let i = 0;
 
+  // Setea valor en ambas formas (con dashes y con underscores) para que
+  // los consumidores puedan acceder vía opciones['dry-run'] u opciones.dry_run
+  // indistintamente. Resuelve la categoría de bugs donde el parser convertía
+  // dashes a underscores solo para flags de whitelist, dejando otros con dashes
+  // — inconsistencia que llevaba a wrappers buscando la clave equivocada y a
+  // flags silenciosamente ignorados.
+  const setear = (clave, valor) => {
+    opciones[clave] = valor;
+    const conUnderscores = clave.replace(/-/g, '_');
+    if (conUnderscores !== clave) {
+      opciones[conUnderscores] = valor;
+    }
+  };
+
   while (i < args.length) {
     const arg = args[i];
 
     if (arg.startsWith('--')) {
-      const clave = arg.slice(2);
-      // Opciones booleanas
+      let clave = arg.slice(2);
+      // Soporta flags con valor integrado: --key=value
+      // Antes el parser dejaba 'session=claude' como nombre de flag completo,
+      // produciendo opciones['session=claude']=true en vez de opciones.session='claude'.
+      let valorIntegrado = null;
+      const idxIgual = clave.indexOf('=');
+      if (idxIgual !== -1) {
+        valorIntegrado = clave.slice(idxIgual + 1);
+        clave = clave.slice(0, idxIgual);
+      }
+
+      // Opciones booleanas explícitas (whitelist) — siempre booleanas
       if (['global', 'local', 'dry-run', 'force', 'verbose', 'all', 'all-langs', 'no-claudemd'].includes(clave)) {
-        opciones[clave.replace(/-/g, '_')] = true;
+        setear(clave, true);
+      } else if (valorIntegrado !== null) {
+        // --key=value
+        setear(clave, valorIntegrado);
       } else if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
-        opciones[clave] = args[i + 1];
+        // --key value
+        setear(clave, args[i + 1]);
         i++;
       } else {
-        opciones[clave] = true;
+        // --key (sin valor)
+        setear(clave, true);
       }
     } else if (arg.startsWith('-')) {
       const clave = arg.slice(1);

package/comandos/swl/aprender.md

@@ -361,7 +361,7 @@ Antes de pasar al Paso 7, ejecutar OBLIGATORIAMENTE el verificador que valida qu
 ```bash
 # Verifica archivos modificados desde el último commit del usuario
 # (ajustar --since según el alcance de la sesión de aprender)
-node scripts/verificar-evolucion.js --changed --since=HEAD~1
+npx -y @saulwade/swl-ses@latest verify-evolution --changed --since=HEAD~1
 ```
 
 El script revisa cada agente/skill modificado contra 4 criterios: