npm - @saulwade/swl-ses - Versions diffs - 1.5.0 → 1.5.1 - Mend

@saulwade/swl-ses 1.5.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CLAUDE.md +209 -208
package/README.md +1 -1
package/habilidades/meta-skills-estandar/SKILL.md +22 -1
package/habilidades/node-experto/SKILL.md +13 -2
package/habilidades/tdd-workflow/SKILL.md +33 -4
package/habilidades/verificar-trabajo/SKILL.md +8 -3
package/package.json +2 -2
package/plugin.json +1 -1
package/scripts/doctor.js +31 -4

package/CLAUDE.md CHANGED Viewed

@@ -1,208 +1,209 @@
-# CLAUDE.md — @saulwade/swl-ses v1.5.0
-## 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)
-- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
-- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
-- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
-- **Secretos per-equipo van en `.claude/settings.local.json` (gitignored), no en `.claude/settings.json` (versionado)**: el archivo `settings.json` se sincroniza entre equipos vía git, así que NO puede contener valores per-máquina como apiKeys. Claude Code hace **deep merge** entre `settings.json` y `settings.local.json` — el local sobrescribe solo las keys que define. Patrón obligatorio para `OBSIDIAN_API_KEY` y similares: `settings.json` declara el server MCP con `env: {}` vacío; `settings.local.json` (cada equipo el suyo) tiene `mcpServers.obsidian.env.OBSIDIAN_API_KEY` con el valor del plugin Local REST API de ESE equipo. **NUNCA** poner dos `OBSIDIAN_API_KEY` en el mismo `env` — produce JSON inválido (síntoma: ConnectionRefused o 40101 silenciosos). Origen: PR #19 sesión 2026-05-13 (bug detectado al cambiar de WISC a WISCLAP)
-## 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`
-- **`package.json#files` debe incluir TODOS los directorios referenciados por `bin/`, `hooks/`, `scripts/` o `comandos/`**: si un binario hace `require('./gateway/foo')` pero `gateway/` no está listado en `files`, **el módulo se omite del tarball npm y el binario falla con MODULE_NOT_FOUND tras instalación pública** — aunque la suite local pase. Bug latente histórico: `/swl:cron`, `/swl:gateway` e `/swl:inbox` instruyen `require('./gateway/...')` y rompían en npm porque `gateway/` no estaba en `files` desde versiones previas. Revelado al agregar `bin/swl-webhook-server` (v1.4.0). Verificar antes de cada release: `npm pack --dry-run | grep -E "^npm notice [0-9].*[Bb] (bin|gateway|hooks|scripts|comandos)/"` debe listar todos los directorios reales referenciados. Gate automatizable en `scripts/verificar-release.js`. Origen: PR #15 sesión 2026-05-13
-## 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, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 60 agentes, 160 skills, 44 comandos, 65 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. `discutir-fase` empieza con discovery routing (5 paths: extender / sin-fase / nueva / decomposición / mixto). `ejecutar-fase --iterative` activa modo per-task con review adversarial. `verificar` clasifica claims (TASK/FIX/TEST_OR_BUILD/FEATURE_GO) para evidencia proporcional. |
-| `/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:verificar --full` activa parallel scorecard con 4 audits paralelos |
-| `/swl:nemesis` | Auditoría iterativa Feynman + State Inconsistency (loop hasta convergencia, ADR-0018). Flags: `--pass1`, `--pass2`, `--continue`, `--modulo <ruta>` |
-| `/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 (25 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 o vía `@reglas/<nombre>.md` desde el CLAUDE.md del
-proyecto. Reglas de mayor uso:
-| Regla | Carga cuando |
-|-------|-------------|
-| `usar-sistema-swl.md` | Siempre — matriz operacional: tarea → componente SWL obligatorio |
-| `brevedad-output.md` | Siempre — idioma español, 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.
-@reglas/usar-sistema-swl.md
-## 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.5.1
+## 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) |
+| `node scripts/derivar-feature-list.js` | Genera `.planning/feature-list.json` (derivado de `HOJA-RUTA.md`, gitignored, regenerable). Modo `--check` exit 2 si drift detectado. Consumido por `/swl:metricas fases`. |
+## 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)
+- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
+- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
+- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
+- **Secretos per-equipo van en `.claude/settings.local.json` (gitignored), no en `.claude/settings.json` (versionado)**: el archivo `settings.json` se sincroniza entre equipos vía git, así que NO puede contener valores per-máquina como apiKeys. Claude Code hace **deep merge** entre `settings.json` y `settings.local.json` — el local sobrescribe solo las keys que define. Patrón obligatorio para `OBSIDIAN_API_KEY` y similares: `settings.json` declara el server MCP con `env: {}` vacío; `settings.local.json` (cada equipo el suyo) tiene `mcpServers.obsidian.env.OBSIDIAN_API_KEY` con el valor del plugin Local REST API de ESE equipo. **NUNCA** poner dos `OBSIDIAN_API_KEY` en el mismo `env` — produce JSON inválido (síntoma: ConnectionRefused o 40101 silenciosos). Origen: PR #19 sesión 2026-05-13 (bug detectado al cambiar de WISC a WISCLAP)
+## 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`
+- **`package.json#files` debe incluir TODOS los directorios referenciados por `bin/`, `hooks/`, `scripts/` o `comandos/`**: si un binario hace `require('./gateway/foo')` pero `gateway/` no está listado en `files`, **el módulo se omite del tarball npm y el binario falla con MODULE_NOT_FOUND tras instalación pública** — aunque la suite local pase. Bug latente histórico: `/swl:cron`, `/swl:gateway` e `/swl:inbox` instruyen `require('./gateway/...')` y rompían en npm porque `gateway/` no estaba en `files` desde versiones previas. Revelado al agregar `bin/swl-webhook-server` (v1.4.0). Verificar antes de cada release: `npm pack --dry-run | grep -E "^npm notice [0-9].*[Bb] (bin|gateway|hooks|scripts|comandos)/"` debe listar todos los directorios reales referenciados. Gate automatizable en `scripts/verificar-release.js`. Origen: PR #15 sesión 2026-05-13
+## 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, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 60 agentes, 160 skills, 44 comandos, 65 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. `discutir-fase` empieza con discovery routing (5 paths: extender / sin-fase / nueva / decomposición / mixto). `ejecutar-fase --iterative` activa modo per-task con review adversarial. `verificar` clasifica claims (TASK/FIX/TEST_OR_BUILD/FEATURE_GO) para evidencia proporcional. |
+| `/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:verificar --full` activa parallel scorecard con 4 audits paralelos |
+| `/swl:nemesis` | Auditoría iterativa Feynman + State Inconsistency (loop hasta convergencia, ADR-0018). Flags: `--pass1`, `--pass2`, `--continue`, `--modulo <ruta>` |
+| `/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 (25 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 o vía `@reglas/<nombre>.md` desde el CLAUDE.md del
+proyecto. Reglas de mayor uso:
+| Regla | Carga cuando |
+|-------|-------------|
+| `usar-sistema-swl.md` | Siempre — matriz operacional: tarea → componente SWL obligatorio |
+| `brevedad-output.md` | Siempre — idioma español, 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.
+@reglas/usar-sistema-swl.md
+## 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 CHANGED Viewed

@@ -1,4 +1,4 @@
-# swl-ses v1.5.0
+# swl-ses v1.5.1
 > 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/habilidades/meta-skills-estandar/SKILL.md CHANGED Viewed

@@ -9,7 +9,12 @@ description: >
   idiomas de framework y mapeo a frameworks de seguridad. Cargar cuando se
   esté escribiendo o auditando un SKILL.md y se necesiten patrones avanzados
   que no están en la regla core.
-version: "1.0.0"
+version: "1.0.1"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-15"
+evolved-by: "aprender"
+evolved-note: "Gotcha 'absorber naming externo al portar patrón valioso' agregado. Origen: instrucción explícita del usuario en sesión 2026-05-15 al renombrar 'kiro-review-protocol' → 'protocolo-revision-swl' durante absorción cc-sdd."
 herramientasPermitidas: [Read, Write, Edit]
 exclusiones:
   - "No cargar si solo se necesita el frontmatter obligatorio, el límite de líneas o la estructura de directorio — eso está en la regla core `reglas/skills-estandar.md` que se carga siempre."
@@ -293,6 +298,22 @@ al caso en cuestión en lugar de los tres.
 - **Cargar este skill cuando la regla core basta**: esto invierte el trade-off
   de context budget. Cargar `meta-skills-estandar` solo cuando se necesita
   contenido extendido, no por defecto.
+- **Absorber naming externo al portar un patrón valioso**: cuando un skill
+  externo (de cc-sdd, harness-sdd, langchain, kiro, etc.) aporta un patrón
+  útil, la tentación es importar también el nombre original (`kiro-review`,
+  `kiro-impl`, `langchain-router`). Causa: economía cognitiva en la transición.
+  Costo: rompe la identidad del sistema receptor, confunde routing del
+  orquestador, viola la regla de idioma español MX y crea acoplamiento
+  conceptual con un sistema externo cuya API puede cambiar. Solución
+  obligatoria: **portar el patrón, adaptar el nombre al naming del sistema
+  receptor**. Para SWL: usar prefijo `swl-` o sufijo `-swl`, en español MX,
+  con el dominio del problema (no del sistema origen). Ejemplo real
+  (2026-05-15): el patrón `kiro-review` de cc-sdd se absorbió como
+  `protocolo-revision-swl` por instrucción explícita del usuario; `kiro-impl`
+  iterativo se absorbió como `ejecutar-task-iterativo`. Documentar el origen
+  en la sección "Referencias" o "Origen" del skill, NO en el nombre. Verificar
+  con `git log --grep="kiro\|otro-prefijo-externo"` que no quedan menciones
+  del naming externo en el codebase del sistema receptor.
 ## Referencias

package/habilidades/node-experto/SKILL.md CHANGED Viewed

@@ -4,9 +4,9 @@ description: Node.js y TypeScript backend moderno. Cubre patterns de Express/Fas
 version: "1.0.1"
 evolved: true
 evolved-from: "1.0.0"
-evolved-at: "2026-05-14"
+evolved-at: "2026-05-15"
 evolved-by: "aprender"
-evolved-note: "Gotcha req.destroy() vs req.pause() en handlers HTTP nativos — origen PR #13 webhook-server"
+evolved-note: "Gotcha req.destroy() vs req.pause() en HTTP nativos (PR #13). + CRLF regex breakage en Windows + serializar TOML con literal '''...''' (Sub-fase 11/11.5 v1.5.1)."
 herramientasPermitidas: [Read, Write, Glob]
 exclusiones:
   - "No cargar para aplicaciones Next.js con App Router — Next.js tiene patrones de Server Components, SSR y caché que difieren del backend Node puro; cargar `nextjs-experto`."
@@ -272,6 +272,17 @@ if (require.main === module) {
 **`req.destroy()` en un handler `http` cierra el socket antes de poder enviar la respuesta**: cuando se aborta la lectura del body (por ejemplo al exceder `maxPayloadBytes`), llamar `req.destroy()` en el listener `data` cierra el socket inmediatamente. El subsiguiente `res.writeHead(413); res.end()` del handler falla porque ya no hay socket — el cliente recibe `ECONNRESET` en lugar de 413. Causa: `destroy()` no espera al flush de la respuesta pendiente; equivale a un `RST` TCP. Fix: usar `req.pause()` + un flag `abortado = true` + rechazar la promesa de lectura; dejar que el handler envíe `res.writeHead(413); res.end(...)` normalmente. Node cierra el socket por sí solo tras `res.end()`. Aplica a servidores HTTP nativos sin Express/Fastify, donde el control del body es manual.
+**Regex multi-line con `\n` falla con archivos CRLF de Windows**: un parser que usa `/^---\n([\s\S]*?)\n---\n/` para detectar frontmatter YAML rompe con archivos commiteados en Windows (donde git aplica `core.autocrlf=true` y convierte LF↔CRLF al checkout). Caso real (Sub-fase 11.5 v1.5.1, swl-ses): `parsearFrontmatter` en `scripts/lib/transformadores/base.js` devolvía `frontmatter:{}` y `cuerpo:<archivo entero>` para los 60 agentes `agentes/*.md` cuando se ejecutaba en Windows. Resultado downstream: `transformarAgente` de Codex generaba TOML con `description = ""` y `developer_instructions` con el frontmatter duplicado dentro del body. Bug latente que solo aparece al ejecutar contra archivos reales con CRLF. Fix: normalizar antes del match — `const norm = String(contenido).replace(/\r\n/g, '\n').replace(/\r/g, '\n');` y aplicar regex sobre `norm`. Siempre asumir que cualquier archivo leído de filesystem en Windows puede tener CRLF, incluso si git lo "almacena" como LF. Aplica a TODA función con regex multi-line que reciba contenido de filesystem.
+**Serializar TOML zero-deps: preferir `'''literal'''` sobre `"""basic"""` para multi-line con backslashes**: TOML soporta dos sintaxis multi-line — basic `"""..."""` que procesa escapes (`\n`, `\t`, `\\`) y literal `'''...'''` que preserva el contenido tal cual. Caso real (Sub-fase 11 v1.5.1, swl-ses): al serializar el cuerpo Markdown de agentes SWL (con regex `\n`, paths Windows con `\`, etc.) a `developer_instructions` de `~/.codex/agents/*.toml`, usar basic `"""..."""` exigía escapar cada `\` a `\\` (laborioso y propenso a bugs). Solución: usar literal `'''...'''` por default (preserva Markdown crudo) y caer a basic `"""..."""` con escape SOLO si el cuerpo contiene `'''` literal (raro). Helper en `scripts/lib/transformadores/codex.js`:
+```js
+_tomlMultiline(s) {
+  if (!s.includes("'''")) return `'''\n${s}\n'''`;
+  return `"""\n${s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""`;
+}
+```
+Aplica a cualquier serialización TOML manual sin librería (`@iarna/toml`, etc.) donde el contenido es texto rico con caracteres especiales.
 ```js
 // MAL — ECONNRESET en cliente, nunca recibe 413
 req.on('data', chunk => {

package/habilidades/tdd-workflow/SKILL.md CHANGED Viewed

@@ -1,12 +1,12 @@
 ---
 name: tdd-workflow
 description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.0.2"
+version: "1.0.3"
 evolved: true
-evolved-from: "1.0.1"
-evolved-at: "2026-05-14"
+evolved-from: "1.0.2"
+evolved-at: "2026-05-15"
 evolved-by: "aprender"
-evolved-note: "Patrón reloj inyectable (parámetro `ahora` con default Date.now()) para tests deterministas sin freezegun/jest.useFakeTimers — validado en 3 módulos sesión webhook Opción C"
+evolved-note: "Gotcha process.cwd() cacheado al require() rompe tests con process.chdir(): fix con parámetro cwd opcional + fallback dinámico. Caso real scripts/derivar-feature-list.js v1.5.0."
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -330,3 +330,32 @@ assert.equal(b.consumir(5, T0 + 5000), true);      // 5 seg después: 5 tokens
 Aplica también a tests de clock skew (tiempo retrocede por NTP): pasar `T0 - 1000` y validar que la lógica no rompe. Origen: rate-limit-ip.js + webhook-dedup.js sesión 2026-05-13.
 **Tests nombrados por feature (`test_emitir_factura_exitosa`) pierden poder regresivo; nombrados por causa raíz (`test_repository_no_usa_columna_inexistente_p_monto`) detectan regresiones específicas sin reproducción manual** [CONFIRMADO en SIGM Opción C F1.4]: cuando se descubre un bug por una causa raíz concreta (typo en nombre de columna SQL, omisión de `selectinload`, mock que devuelve dict en vez de objeto, schema obsoleto), el test de regresión que se escribe debe llevar el nombre de la causa, no del feature afectado. Caso real: durante F1.4 de SIGM, el repository de pagos referenciaba `p.monto` cuando la columna se llamaba `p.monto_pagado`; el test escrito como `test_repository_no_usa_columna_inexistente_p_monto` falló inmediatamente en la siguiente sesión cuando otro agente reintrodujo el typo, sin necesidad de reproducir el escenario de negocio (emitir cobro real, verificar respuesta). Causa: los nombres orientados a feature (`test_pago_exitoso`) son ambiguos sobre QUÉ falla — si el test falla, el desarrollador debe diagnosticar; los nombres orientados a causa raíz (`test_X_no_usa_Y`, `test_query_incluye_selectinload_Z`, `test_service_devuelve_dict_no_objeto`) son auto-diagnósticos. Fix: para cada bug que cueste >30 min diagnosticar, escribir UN test adicional cuyo nombre describa la condición técnica violada, no el escenario de negocio. Convención: `test_<componente>_<condicion_tecnica>` o `test_<componente>_no_<anti_patron>`. Estos tests son tu segunda línea de defensa contra regresiones de la misma causa raíz, complementarios a los tests de comportamiento.
+**`process.cwd()` cacheado al `require()` rompe tests con `process.chdir(sandbox)`** [PATRÓN GENÉRICO TESTING CLI]: scripts Node exportables que leen `process.cwd()` en el scope del módulo (al cargar) congelan el cwd al directorio de invocación. Los tests que crean sandboxes con `fs.mkdtempSync()` y luego `process.chdir(sandbox)` no afectan al cwd cacheado — el script sigue leyendo del cwd original y los assertions fallan con paths inesperados. Caso real (swl-ses `scripts/derivar-feature-list.js` 2026-05-15): la función `enriquecerDesdeFases(fases)` leía `const CWD = process.cwd()` calculado al `require()`; 2 tests con `process.chdir(sandbox)` retornaron `[]` en lugar de detectar el PLAN.md fixture. Causa: el constante se evaluó cuando el `node --test` cargó el módulo desde el cwd del proyecto, no desde el sandbox del test individual. Fix obligatorio: funciones exportables deben aceptar `cwd` como parámetro opcional con fallback dinámico (`function fn(args, opciones = {}) { const cwd = opciones.cwd || process.cwd(); ... }`). El código de producción no cambia (sin args extras), pero los tests pueden inyectar el cwd correcto. Aplica también a Python (`def fn(args, cwd: str | None = None): cwd = cwd or os.getcwd()`) y a cualquier lenguaje con tests que usen chdir.
+```js
+// MAL — cwd cacheado al require, tests con process.chdir() fallan
+const CWD = process.cwd();
+const PLANNING_DIR = path.join(CWD, '.planning');
+function enriquecerDesdeFases(fases) {
+  const archivos = fs.readdirSync(path.join(PLANNING_DIR, 'fases'));  // cwd congelado
+  // ...
+}
+// BIEN — cwd dinámico con parámetro opcional para tests
+function enriquecerDesdeFases(fases, opciones = {}) {
+  const cwd = opciones.cwd || process.cwd();  // recalcula al llamar
+  const archivos = fs.readdirSync(path.join(cwd, '.planning', 'fases'));
+  // ...
+}
+// En el test:
+const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
+fs.mkdirSync(path.join(sandbox, '.planning', 'fases'), { recursive: true });
+// Opción A: pasar cwd explícito (recomendado)
+const r = enriquecerDesdeFases([], { cwd: sandbox });
+// Opción B: process.chdir() — solo funciona con cwd dinámico
+process.chdir(sandbox);
+const r2 = enriquecerDesdeFases([]);
+```

package/habilidades/verificar-trabajo/SKILL.md CHANGED Viewed

@@ -1,12 +1,12 @@
 ---
 name: verificar-trabajo
 description: Verificación goal-backward del trabajo ejecutado en 4 niveles progresivos — EXISTE, SUSTANTIVO, CONECTADO, DATOS_FLUYEN. Clasifica claims en 4 tipos (TASK, FIX, TEST_OR_BUILD, FEATURE_GO) con evidencia proporcional. Detecta stubs, componentes huérfanos, integraciones rotas y flujos incompletos. Produce veredictos estructurados JSON con clasificación de riesgo (Low/Medium/High) y evidencia verificable. Soporta loop de reparación cuando el veredicto es Fail.
-version: "1.2.0"
+version: "1.2.1"
 evolved: true
-evolved-from: "1.1.1"
+evolved-from: "1.2.0"
 evolved-at: "2026-05-15"
 evolved-by: "aprender"
-evolved-note: "Taxonomía de claim types adoptada de cc-sdd kiro-verify-completion: cada tipo de claim (TASK/FIX/TEST_OR_BUILD/FEATURE_GO) requiere evidencia distinta. Previene declarar éxito broader que la evidencia disponible."
+evolved-note: "Gotchas v1.5.1 acumulados en este ciclo: (1) health-check post-hoc que recalcula contexto del install desde cwd actual → falso positivo (caso doctor 2026-05-15); (2) smoke E2E obligatorio para features cross-cutting (Sub-fase 11.5: transformarAgente nunca invocado pese a suite 100% verde); (3) auto-reparación debe verificar que el chequeo subsecuente ya no detecta el problema, si no → loop infinito (Sub-fase 12: doctor)."
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar durante la implementación activa de una tarea; la verificación es posterior a la implementación, no concurrente."
@@ -340,6 +340,11 @@ estructurado JSON, ver [recursos/plantilla-verificacion.md](recursos/plantilla-v
 - **Loop de reparación sin re-verificación completa**: tras el fix, el agente re-verifica solo el item que falló en lugar del veredicto completo. Causa: optimización incorrecta para ahorrar tiempo. Solución: el paso 3 del loop de reparación dice explícitamente "re-ejecutar la verificación COMPLETA" — un fix puede resolver un fallo pero introducir otro.
 - **Hollow Component no detectado en Nivel 2**: el componente Angular tiene template pero no usa ninguna señal del componente. El agente verifica que el archivo existe (Nivel 1) y que tiene contenido (Nivel 2), pero no detecta que el contenido es decorativo. Causa: la definición de "stub" en Nivel 2 no se aplicó al caso de templates sin binding. Solución: verificar explícitamente que el template usa al menos una variable/señal del componente.
 - **Verificación con tests + linter pasa pero al levantar BD fresca todo se rompe**: tests Python con mocks y `ruff check` retornan verde, pero `docker compose down -v && up` falla porque hay drift entre `database/schemas/`, seeds, funciones SQL y vistas. Caso real (SIGM 2026-05-04): primera pasada de `/swl:verificar` reportó "APROBADO 21/22" sin detectar que ~10 seeds tenían columnas obsoletas, UUIDs inválidos y un script `02-crear-buckets-minio.sh` que abortaba initdb del contenedor postgres. Causa: la verificación corre solo contra el código (que mockea BD); nunca aplica el SQL real. Solución: cuando el alcance toca cualquier archivo en `database/schemas/`, `database/seeds/`, `database/functions/` o `database/views/`, ejecutar como Nivel 4 (DATOS_FLUYEN) obligatorio: `docker compose down -v && docker compose up -d db && wait_for_health && docker logs <db_container> | grep -E "ERROR|skipped"`. Cualquier ERROR en logs de init invalida el veredicto Pass.
+- **Health-check post-hoc que recalcula contexto del install desde cwd actual produce falso positivo**: un verificador (doctor, validador, monitor) que recalcula filtros — aplicados al momento del install — desde el `process.cwd()` actual genera discrepancia falsa cuando se ejecuta desde un dir distinto. Caso real (swl-ses doctor v1.4.3, 2026-05-15): reportaba "reglas: 65 (perfil esperaba 25)" porque recalculaba `filtrarReglasPorStack(detectarStack(cwd))` con `cwd` vacío de indicadores, mientras las 40 reglas-lenguajes se habían instalado correctamente con stack detectado en el dir del proyecto. Causa: el filtro depende del contexto del momento del install, no del momento del check. Solución obligatoria: **persistir el contexto del install en el state file** (en este caso `allLangs` + `stackInstalado` en `.swl-install-state.json`). Si el state es legacy (sin estos campos), **inferir el contexto desde los archivos realmente instalados** (ej: subdirs presentes bajo `reglas/lenguajes/<lang>/`), NO recalcular desde cwd. Aplica como regla general a cualquier check post-hoc cuya validez depende del contexto del install.
+- **Suite 100% verde con bug latente cross-cutting que solo aparece en smoke E2E real**: las unit tests del transformador pasaban, los tests del instalador pasaban, los tests del manifiesto pasaban — pero el smoke `install --target codex --local --force` reveló que `instalarArchivo()` hacía `fs.copyFileSync(archivo.origen, destino)` literal sin invocar `transformarAgente()`. Los `.toml` de Codex y los `.md` normalizados de Cursor NUNCA se generaban en disco aunque las unit tests del transformador retornaran contenido correcto. Caso real (Sub-fase 11.5 v1.5.1, 2026-05-15): la integración de las dos capas (transformador + instalador) jamás se testeaba E2E porque cada una se probaba en aislamiento con mocks. **Regla obligatoria para features cross-cutting** (multi-capa: transformador + instalador + filesystem; o lib + bin + cliente; o backend + frontend + cache): el Nivel 4 DATOS_FLUYEN exige al menos un smoke E2E real que ejercite las tres capas con archivos reales en disco temporal. NO sustituible por unit tests aunque la suite sea 100% verde. Comando mínimo: `mkdir tmp && cd tmp && bin/CLI <comando-happy-path> && ls -R` + inspección del primer archivo generado.
+- **Auto-reparación ejecuta acción sin verificar que el chequeo subsecuente ya no detecta el problema**: el doctor reporta "faltan reglas: 0/25" en Codex, el usuario elige "reparar automáticamente", el doctor invoca `instalador.install({force:true})`, reinstala 230 archivos, vuelve a chequear y reporta lo mismo. Loop infinito. Caso real (Sub-fase 12 v1.5.1, 2026-05-15): los 4 falsos positivos del doctor sobre Codex/Cursor persistían tras cada "reparación" porque la causa raíz era un filtro hardcoded (`tiposPrincipales = ['agentes', 'habilidades', 'comandos', 'reglas']` sin respetar `runtime.tiposSoportados` ni `dir<Tipo>`). Cada reinstalación dejaba el filtro intacto, el chequeo seguía detectando el "problema". **Regla**: toda función de auto-reparación debe ejecutar el chequeo subsecuente ANTES de reportar "Reparado" — si el chequeo sigue detectando el problema, NO marcar como reparado y reportar "no se pudo reparar, requiere diagnóstico manual". Implementación: wrap la acción en `try { accion(); const res = chequeo(); if (!res.ok) throw new Error('reparación sin efecto'); }`.
 ## Regla de oro del verificador

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@saulwade/swl-ses",
-  "version": "1.5.0",
-  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 60 agentes, 158 habilidades, 44 comandos, 65 reglas y 41 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI (soporte completo), Cursor, Codex CLI y GitHub Copilot (soporte parcial — reglas + MCP swl-memory v1.0.0 con auth opt-in). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes) y autoconfig MCP en Cursor/Codex con --with-mcp. Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con 8 tools ejecutables.",
+  "version": "1.5.1",
+  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 60 agentes, 160 habilidades, 44 comandos, 65 reglas y 41 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI, Cursor, Codex CLI (soporte completo); GitHub Copilot (soporte parcial). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes), autoconfig MCP en Cursor/Codex con --with-mcp, agentes Codex en TOML, hooks Cursor (17 eventos) y Codex (6 eventos). Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con 8 tools ejecutables.",
   "bin": {
     "swl-ses": "bin/swl-ses.js",
     "swl-telegram-bot": "bin/swl-telegram-bot.js",

package/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "swl-ses",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 60 agentes, 158 habilidades, 44 comandos, 65 reglas y 41 hooks. 62 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI.",
   "author": "Saul Wade Leon",
   "license": "MIT",

package/scripts/doctor.js CHANGED Viewed

@@ -324,8 +324,14 @@ async function doctor(opciones = {}) {
   // 5b-2. Verificar conteo de componentes contra perfil esperado.
   // Bug H v1.3.5: antes solo verificaba runtime.local; instalaciones globales
   // (~/.claude/) quedaban sin check de conteo. Ahora itera ambos scopes.
+  // Sub-fase 12 v1.5.0: deduplicar paths cuando cwd === homedir (runtime.local
+  // y runtime.global colapsan al mismo directorio) — evita reporte doble.
   for (const runtime of runtimes) {
-    for (const dir of [runtime.global, path.resolve(runtime.local)]) {
+    const dirsUnicos = Array.from(new Set([
+      path.resolve(runtime.global),
+      path.resolve(runtime.local),
+    ]));
+    for (const dir of dirsUnicos) {
     if (!fs.existsSync(dir)) continue;
     const estado = cargarEstado(dir);
     if (!estado || !estado.perfil) continue;
@@ -367,8 +373,21 @@ async function doctor(opciones = {}) {
         resolucion.archivos = filtrado.archivos;
       }
-      // Contar esperados por tipo (solo tipos principales)
-      const tiposPrincipales = ['agentes', 'habilidades', 'comandos', 'reglas'];
+      // Sub-fase 12 v1.5.0: filtrar tipos principales por runtime.tiposSoportados
+      // Y por la presencia de `dir<Tipo>` no-null. Codex declara `reglas` en
+      // tiposSoportados pero las consolida en AGENTS.md (dirReglas: null) — los
+      // archivos individuales no existen aunque el resolver los liste como esperados.
+      // Reportar "faltan reglas: 0/N" en ese caso es falso positivo que dispara
+      // loop infinito de auto-reparación.
+      const TIPO_A_DIR = {
+        agentes: 'dirAgentes',
+        habilidades: 'dirHabilidades',
+        comandos: 'dirComandos',
+        reglas: 'dirReglas',
+      };
+      const tiposPrincipales = ['agentes', 'habilidades', 'comandos', 'reglas']
+        .filter(t => !runtime.tiposSoportados || runtime.tiposSoportados.includes(t))
+        .filter(t => runtime[TIPO_A_DIR[t]]);
       const esperadosPorTipo = {};
       for (const archivo of resolucion.archivos) {
         const tipo = archivo.tipo || 'otros';
@@ -451,8 +470,16 @@ async function doctor(opciones = {}) {
     }
   }
-  // 5c. Verificar optimizaciones de rendimiento en settings.json
+  // 5c. Verificar optimizaciones de rendimiento en settings.json.
+  // Sub-fase 12 v1.5.0: las optimizaciones `ENABLE_TOOL_SEARCH` y
+  // `showThinkingSummaries` son específicas de Claude Code `settings.json`.
+  // Codex usa `config.toml` con schema TOML; Cursor usa schema propio.
+  // Aplicar estas claves a Codex/Cursor poluciona su config con keys que
+  // no tienen efecto. Restringir el check al runtime claude/openclaude.
+  const RUNTIMES_CON_OPTIMIZACIONES = new Set(['claude', 'openclaude']);
   for (const runtime of runtimes) {
+    if (!RUNTIMES_CON_OPTIMIZACIONES.has(runtime.id)) continue;
     const dir = path.resolve(runtime.local);
     if (!fs.existsSync(dir)) continue;
     const estado = cargarEstado(dir);