@saulwade/swl-ses 2.6.0 → 2.6.1

package/hooks/lib/raiz-proyecto.js

@@ -1,102 +1,127 @@
-'use strict';
-
-/**
- * raiz-proyecto.js — Resolución de la raíz del proyecto para hooks que
- * escriben telemetría/memoria en `.planning/`.
- *
- * El CWD de arranque de una sesión NO es la frontera del proyecto: en un
- * monorepo con sesiones abiertas en subdirectorios (`backend/`, `frontend/`),
- * anclar `.planning/` a `process.cwd()` fragmenta la memoria del proyecto en
- * árboles huérfanos (DT-HOOKS-RAIZ-GIT; misma clase que el fix de
- * proteccion-rutas). La frontera correcta es la raíz del repositorio git,
- * con una excepción: un sub-proyecto anidado que ya tiene su propio
- * `.planning/` REAL (con marcadores de proyecto) conserva su árbol local.
- *
- * Reglas de resolución (en orden):
- *   1. Ascendiendo desde `desde`, el primer directorio cuyo `.planning/`
- *      contiene un marcador de proyecto (PROYECTO.md, HOJA-RUTA.md,
- *      ESTADO.md) gana — respeta sub-proyectos legítimos en monorepos.
- *      Un `.planning/` sin marcadores (solo telemetría huérfana de hooks)
- *      NO cuenta: eso es el síntoma del bug, no un proyecto.
- *   2. Si ningún nivel tiene `.planning/` real, gana la raíz del repo git
- *      (`.git` como directorio o como archivo — worktrees).
- *   3. Sin `.git` alcanzable: fallback al propio `desde`.
- *
- * La ascensión se detiene en el HOME del usuario (sin incluirlo) cuando se
- * llega ahí subiendo: un dotfiles-repo en `~` no debe capturar la memoria
- * de un proyecto sin git que viva debajo.
- *
- * Zero-deps (regla de hooks/lib/). Consumidor inicial:
- * hooks/extraccion-aprendizajes.js; la flota completa migró el 2026-07-10
- * (cierre de DT-HOOKS-RAIZ-GIT).
- *
- * LÍMITE DE USO (hallazgo revisor-seguridad 2026-07-10): esta ancla es SOLO
- * para DATOS (.planning/, instintos/, lecturas de config del proyecto).
- * NUNCA resolver con ella EJECUTABLES ni módulos a require()/spawn(): la
- * raíz resuelta pertenece al árbol del proyecto, y un repositorio no
- * confiable puede plantar el script (marcador .planning/PROYECTO.md +
- * scripts/x.js hostil = ejecución de código al disparar el hook). Los
- * ejecutables de la distribución SWL se resuelven desde __dirname
- * (ubicación instalada del hook). Test guardián:
- * tests/hooks/ejecutables-desde-instalacion.test.js.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const MARCADORES_PROYECTO = ['PROYECTO.md', 'HOJA-RUTA.md', 'ESTADO.md'];
-const MAX_NIVELES = 40;
-
-/**
- * ¿El directorio tiene un `.planning/` de proyecto real (no huérfano)?
- * @param {string} dir
- * @returns {boolean}
- */
-function tienePlanningReal(dir) {
-  try {
-    return MARCADORES_PROYECTO.some(m =>
-      fs.existsSync(path.join(dir, '.planning', m))
-    );
-  } catch (_) {
-    return false;
-  }
-}
-
-/**
- * Resuelve la raíz del proyecto a la que deben anclarse las escrituras
- * de `.planning/`.
- *
- * @param {string} [desde] - Directorio de partida (default: process.cwd()).
- * @returns {string} Ruta absoluta de la raíz del proyecto.
- */
-function raizProyecto(desde) {
-  const inicio = path.resolve(desde || process.cwd());
-  let actual = inicio;
-  let homedir = null;
-  try {
-    homedir = path.resolve(os.homedir());
-  } catch (_) { /* sin home resolvible — seguir sin el guard */ }
-
-  for (let i = 0; i < MAX_NIVELES; i++) {
-    // Frontera del HOME: si llegamos aquí ASCENDIENDO, no seguir — un
-    // dotfiles-repo en ~ no es la raíz de un proyecto que vive debajo.
-    if (homedir && actual === homedir && i > 0) break;
-
-    if (tienePlanningReal(actual)) return actual;
-
-    try {
-      if (fs.existsSync(path.join(actual, '.git'))) return actual;
-    } catch (_) {
-      break;
-    }
-
-    const padre = path.dirname(actual);
-    if (padre === actual) break; // raíz del filesystem
-    actual = padre;
-  }
-
-  return inicio;
-}
-
-module.exports = { raizProyecto, tienePlanningReal };
+'use strict';
+
+/**
+ * raiz-proyecto.js — Resolución de la raíz del proyecto para hooks que
+ * escriben telemetría/memoria en `.planning/`.
+ *
+ * El CWD de arranque de una sesión NO es la frontera del proyecto: en un
+ * monorepo con sesiones abiertas en subdirectorios (`backend/`, `frontend/`),
+ * anclar `.planning/` a `process.cwd()` fragmenta la memoria del proyecto en
+ * árboles huérfanos (DT-HOOKS-RAIZ-GIT; misma clase que el fix de
+ * proteccion-rutas). La frontera correcta es la raíz del repositorio git,
+ * con una excepción: un sub-proyecto anidado que ya tiene su propio
+ * `.planning/` REAL (con marcadores de proyecto) conserva su árbol local.
+ *
+ * Reglas de resolución (en orden):
+ *   1. Ascendiendo desde `desde`, el primer directorio cuyo `.planning/`
+ *      contiene un marcador de proyecto (PROYECTO.md, HOJA-RUTA.md,
+ *      ESTADO.md) gana — respeta sub-proyectos legítimos en monorepos.
+ *      Un `.planning/` sin marcadores (solo telemetría huérfana de hooks)
+ *      NO cuenta: eso es el síntoma del bug, no un proyecto.
+ *   2. Si ningún nivel tiene `.planning/` real, gana la raíz del repo git
+ *      (`.git` como directorio o como archivo — worktrees).
+ *   3. Sin `.git` alcanzable: fallback al propio `desde`.
+ *
+ * La ascensión se detiene en el HOME del usuario (sin incluirlo) cuando se
+ * llega ahí subiendo: un dotfiles-repo en `~` — o un `~/.planning` sembrado
+ * por `swl-ses doctor` en una instalación global — no debe capturar la
+ * memoria de un proyecto sin git que viva debajo. La comparación con el HOME
+ * se hace en forma CANÓNICA (realpath): en Windows `os.tmpdir()` puede
+ * devolver el nombre corto 8.3 (`C:\Users\SAUL~1.WAD`) mientras `os.homedir()`
+ * devuelve el largo (`C:\Users\saul.wade`); sin canonicalizar, la frontera no
+ * dispararía y capturaría `~/.planning` o `~/.git` (rompía 38 tests locales
+ * en Windows, verde en CI Linux porque `/tmp` no cuelga de `$HOME`).
+ *
+ * Zero-deps (regla de hooks/lib/). Consumidor inicial:
+ * hooks/extraccion-aprendizajes.js; la flota completa migró el 2026-07-10
+ * (cierre de DT-HOOKS-RAIZ-GIT).
+ *
+ * LÍMITE DE USO (hallazgo revisor-seguridad 2026-07-10): esta ancla es SOLO
+ * para DATOS (.planning/, instintos/, lecturas de config del proyecto).
+ * NUNCA resolver con ella EJECUTABLES ni módulos a require()/spawn(): la
+ * raíz resuelta pertenece al árbol del proyecto, y un repositorio no
+ * confiable puede plantar el script (marcador .planning/PROYECTO.md +
+ * scripts/x.js hostil = ejecución de código al disparar el hook). Los
+ * ejecutables de la distribución SWL se resuelven desde __dirname
+ * (ubicación instalada del hook). Test guardián:
+ * tests/hooks/ejecutables-desde-instalacion.test.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MARCADORES_PROYECTO = ['PROYECTO.md', 'HOJA-RUTA.md', 'ESTADO.md'];
+const MAX_NIVELES = 40;
+
+/**
+ * ¿El directorio tiene un `.planning/` de proyecto real (no huérfano)?
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function tienePlanningReal(dir) {
+  try {
+    return MARCADORES_PROYECTO.some(m =>
+      fs.existsSync(path.join(dir, '.planning', m))
+    );
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Canonicaliza un path resolviendo enlaces simbólicos y el nombre corto 8.3
+ * de Windows (`C:\Users\SAUL~1.WAD` → `C:\Users\saul.wade`). Solo se usa para
+ * la comparación de la frontera del HOME: el valor de RETORNO de raizProyecto
+ * conserva la forma del argumento recibido, no la canónica. Si el path no
+ * existe (no se puede resolver), cae a `path.resolve`.
+ * @param {string} p
+ * @returns {string}
+ */
+function canonicalizar(p) {
+  try {
+    return fs.realpathSync.native(p);
+  } catch (_) {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * Resuelve la raíz del proyecto a la que deben anclarse las escrituras
+ * de `.planning/`.
+ *
+ * @param {string} [desde] - Directorio de partida (default: process.cwd()).
+ * @returns {string} Ruta absoluta de la raíz del proyecto.
+ */
+function raizProyecto(desde) {
+  const inicio = path.resolve(desde || process.cwd());
+  let actual = inicio;
+  let homedirCanon = null;
+  try {
+    homedirCanon = canonicalizar(path.resolve(os.homedir()));
+  } catch (_) { /* sin home resolvible — seguir sin el guard */ }
+
+  for (let i = 0; i < MAX_NIVELES; i++) {
+    // Frontera del HOME: si llegamos aquí ASCENDIENDO, no seguir — un
+    // dotfiles-repo (o un ~/.planning sembrado por doctor) en ~ no es la raíz
+    // de un proyecto que vive debajo. Comparación canónica: iguala el nombre
+    // corto 8.3 heredado de os.tmpdir() con el HOME largo de os.homedir().
+    if (homedirCanon && i > 0 && canonicalizar(actual) === homedirCanon) break;
+
+    if (tienePlanningReal(actual)) return actual;
+
+    try {
+      if (fs.existsSync(path.join(actual, '.git'))) return actual;
+    } catch (_) {
+      break;
+    }
+
+    const padre = path.dirname(actual);
+    if (padre === actual) break; // raíz del filesystem
+    actual = padre;
+  }
+
+  return inicio;
+}
+
+module.exports = { raizProyecto, tienePlanningReal, canonicalizar };

package/hooks/lib/run-log.js

@@ -38,7 +38,7 @@
  */
 
 const fs      = require('fs');
-const { raizProyecto } = require('./raiz-proyecto');
+const { raizProyecto } = require('./raiz-proyecto');
 const path    = require('path');
 const readline = require('readline');
 const os      = require('os');

package/hooks/lib/singleton-guard.js

@@ -32,6 +32,7 @@ const DIR_LOCKS = path.join(raizProyecto(process.cwd()), '.planning', 'locks');
 const STALE_MS_DEFAULT = 5 * 60 * 1000; // 5 minutos
 const locksAdquiridos = new Set();
 let handlersRegistrados = false;
+let seqTmp = 0; // secuencia para nombres de temp únicos por proceso
 
 function rutaLock(nombre) {
   return path.join(DIR_LOCKS, `${nombre}.lock`);
@@ -60,28 +61,34 @@ function pidVivo(pid) {
 }
 
 /**
- * Escribe el lockfile con exclusión atómica (O_EXCL vía flag 'wx'): falla con
- * EEXIST si el archivo ya existe, sin ventana check-then-write. Es lo que
- * garantiza la exclusión mutua real entre DOS procesos simultáneos —
- * fs.existsSync + fs.writeFileSync NO la garantiza (ambos ven no-existe y
- * ambos escriben; hallazgo re-auditoría nemesis iter-2).
+ * Escribe el lockfile con exclusión atómica y SIN ventana de archivo vacío:
+ * escribe el contenido completo en un temp único y lo ENLAZA (link(2)) a `ruta`.
+ * link es atómico y falla con EEXIST si `ruta` ya existe — misma garantía de
+ * exclusión mutua que O_EXCL — pero, a diferencia de open('wx')+write, `ruta`
+ * NUNCA aparece vacío: el inodo enlazado ya trae el JSON completo.
+ *
+ * Por qué NO open('wx')+write (hallazgo 2026-07-15): esa forma crea el archivo
+ * vacío y ESCRIBE después. Un contendiente en el path de takeover que lo leyera
+ * en esa ventana obtenía '' → JSON.parse lanza → leerLock=null →
+ * contenidoTomable(null)=true → hacía takeover de un lock YA ganado → DOS
+ * holders. Reproducido a ~10% con 16 procesos simultáneos sobre el path stale;
+ * antes no se veía porque el test no forzaba simultaneidad real.
+ * (Precedente: fs.existsSync+writeFileSync tampoco sirve — nemesis iter-2.)
  *
  * @param {string} ruta
  * @param {string} nombre
  * @returns {boolean} true si este proceso creó el lock.
  */
 function crearLockExclusivo(ruta, nombre) {
+  const tmp = `${ruta}.${process.pid}.${++seqTmp}.tmp`;
   try {
-    const fd = fs.openSync(ruta, 'wx'); // O_CREAT | O_EXCL | O_WRONLY
-    try {
-      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: new Date().toISOString(), nombre }));
-    } finally {
-      fs.closeSync(fd);
-    }
+    fs.writeFileSync(tmp, JSON.stringify({ pid: process.pid, ts: new Date().toISOString(), nombre }));
+    fs.linkSync(tmp, ruta); // atómico; lanza EEXIST si `ruta` ya existe
     return true;
   } catch (err) {
-    if (err.code === 'EEXIST') return false;
-    return false;
+    return false; // EEXIST (otro ganó) u otro error de I/O → no se adquirió
+  } finally {
+    try { fs.unlinkSync(tmp); } catch (_) { /* temp ya removido o nunca creado */ }
   }
 }
 

package/hooks/lib/telegram-cliente.js

@@ -130,15 +130,23 @@ function _esperar(ms) {
  *
  * @param {string} token   - Token del bot (`123:ABC...`).
  * @param {string} chatId  - ID numérico del chat destino.
- * @param {string} texto   - Texto del mensaje. Se escapa y trunca automáticamente.
+ * @param {string} texto   - Texto del mensaje. Por default se escapa (el llamador
+ *   pasa texto PLANO). Si el llamador ya construyó HTML válido (tags + contenido
+ *   escapado), pasar `opts.escaparContenido = false` para NO re-escapar — de lo
+ *   contrario los `<b>` se convierten en `&lt;b&gt;` y Telegram los muestra
+ *   literales (doble escape; bug 2026-07-15).
  * @param {object} [opts]  - Campos adicionales para el body de sendMessage.
+ * @param {boolean} [opts.escaparContenido=true] - Escapar HTML del texto (para
+ *   llamadores que pasan texto plano). false si el texto YA es HTML listo.
  * @returns {Promise<{ok: boolean, statusCode: number, error?: string}>}
  */
 async function enviarMensaje(token, chatId, texto, opts = {}) {
-  const textoPrepado = truncar(escaparHtml(texto), LIMITE_CHARS);
+  const { escaparContenido = true, ...payloadOpts } = opts;
+  const base = escaparContenido ? escaparHtml(texto) : String(texto);
+  const textoPrepado = truncar(base, LIMITE_CHARS);
 
   for (let intento = 0; intento < REINTENTOS_MAX; intento++) {
-    const resultado = await _intentarEnvio(token, chatId, textoPrepado, opts);
+    const resultado = await _intentarEnvio(token, chatId, textoPrepado, payloadOpts);
 
     if (resultado.ok) {
       return { ok: true, statusCode: resultado.statusCode };

package/hooks/notificacion-telegram.js

@@ -23,6 +23,7 @@ const path = require('node:path');
 
 const { cargarConfig, estaMuted } = require('./lib/telegram-config');
 const { enviarMensaje, escaparHtml } = require('./lib/telegram-cliente');
+const { resumirParaNotificacion } = require('./lib/notificacion-formato');
 
 // ----------------------------------------------------------------
 // Utilidades de logging
@@ -121,7 +122,7 @@ function construirCampos(nombreEvento, nombreProyecto, transcriptPath, evt) {
   if (nombreEvento === 'Stop' || nombreEvento === 'SubagentStop') {
     tituloBase = nombreEvento === 'SubagentStop' ? 'Subagente terminó' : 'Claude terminó';
     subtitulo  = 'Turno completado';
-    cuerpo     = leerUltimoMensajeAsistente(transcriptPath) || 'Claude terminó el turno.';
+    cuerpo     = resumirParaNotificacion(leerUltimoMensajeAsistente(transcriptPath)) || 'Claude terminó el turno.';
 
   } else if (nombreEvento === 'Notification') {
     tituloBase = 'Claude espera respuesta';
@@ -262,14 +263,23 @@ async function run() {
     `<b>Estado:</b> ${escaparHtml(subtitulo)}\n\n` +
     `${escaparHtml(cuerpo)}`;
 
-  // Enviar notificación Telegram
+  // Enviar notificación Telegram. escaparContenido:false porque `texto` YA es
+  // HTML listo (tags <b> + contenido escapado arriba); re-escaparlo mostraría
+  // los tags literales en Telegram (doble escape, bug 2026-07-15).
   const resultado = await enviarMensaje(
     config.TELEGRAM_BOT_TOKEN,
     config.TELEGRAM_CHAT_ID,
-    texto
+    texto,
+    { escaparContenido: false }
   );
 
   log('telegram resultado', resultado.ok ? 'ok' : resultado.error);
 }
 
+// Sin gate de entrypoint: los hooks se invocan vía el wrapper
+// `node -e "require('./hooks/notificacion-telegram.js')"` de settings.json (y
+// desde los wrappers -notification/-subagent), donde require.main es undefined;
+// un gate de entrypoint dejaría el hook muerto en producción (audit
+// entrypoint-wrapper.test.js). Las funciones puras testeables viven en
+// ./lib/notificacion-formato.js.
 run().catch(e => log('run error', e && e.message));

package/hooks/preservar-estado-pre-compact.js

@@ -20,7 +20,7 @@
  */
 
 const fs   = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 // Atomic write para backups pre-compact (.planning/backups/). Si la

package/hooks/registro-turnos.js

@@ -54,7 +54,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 const LIMITE_TURNOS = parseInt(process.env.SWL_REGISTRO_TURNOS_LIMITE || '1000', 10);

package/hooks/resumen-sesion.js

@@ -18,7 +18,7 @@
  */
 
 const fs     = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path   = require('path');
 const os     = require('os');
 const { execFile } = require('child_process');

package/hooks/risk-scoring.js

@@ -26,7 +26,7 @@
  */
 
 const fs   = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const os   = require('os');
 

package/hooks/session-briefing.js

@@ -19,7 +19,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const { spawn } = require('child_process');
 

package/hooks/spec-gate.js

@@ -32,7 +32,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const crypto = require('crypto');
 

package/hooks/sugerir-regenerar-inventario.js

@@ -27,7 +27,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 // Carpetas cuyo cambio invalida los contadores de INVENTARIO.md

package/hooks/tdd-gate.js

@@ -30,7 +30,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const { execFileSync } = require('child_process');
 

package/hooks/telemetria-agentes.js

@@ -17,7 +17,7 @@
  */
 
 const { registrar } = require('./lib/otlp-exporter');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 
 // Importar esquema de spans con guard de robustez — el hook no debe fallar
 // si el módulo aún no existe en instalaciones anteriores del sistema.

package/hooks/telemetria-skill-routing.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 'use strict';
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 
 /**
  * Hook: telemetria-skill-routing.js

package/hooks/tracking-costos.js

@@ -21,7 +21,7 @@
  */
 
 const fs   = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const os   = require('os');
 

package/hooks/validar-formato-post-subagente.js

@@ -23,7 +23,7 @@
  */
 
 const fs   = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 const CWD = raizProyecto(process.cwd());

package/hooks/validar-intent-spec.js

@@ -44,7 +44,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const crypto = require('crypto');
 

package/hooks/validar-planning-paths.js

@@ -19,7 +19,7 @@
  */
 
 const fs = require('fs');
-const { raizProyecto } = require('./lib/raiz-proyecto');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const crypto = require('crypto');
 

package/llms.txt

@@ -1,29 +1,29 @@
-# swl-ses (@saulwade/swl-ses)
-
-> Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo), distribuido como paquete npm y plugin de Claude Code. 61 agentes, 181 habilidades, 48 comandos, 37 reglas base y 49 hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión 2.6.0.
-
-Archivo generado por `node scripts/generar-inventario.js` — no editar a mano. Las cifras se sincronizan con INVENTARIO.md en cada regeneración.
-
-## Documentación
-
-- [README](README.md): overview público y quickstart
-- [Manual de uso](MANUAL_USO.md): manual operacional completo
-- [Comandos](COMANDOS.md): referencia detallada de cada comando `/swl:*`
-- [Agentes](AGENTS.md): catálogo de agentes con capacidades
-- [Inventario](INVENTARIO.md): conteos oficiales de todos los componentes
-- [Instalación](INSTALACION.md): instalación, perfiles y configuración
-- [Instrucciones del proyecto](CLAUDE.md): convenciones, stack y reglas
-
-## Componentes
-
-- [61 agentes especializados](AGENTS.md): orquestación, implementación por stack, revisión, calidad, diseño — fuente en `agentes/`
-- [181 habilidades cargables bajo demanda](INVENTARIO.md): conocimiento operacional con divulgación progresiva — fuente en `habilidades/`
-- [48 comandos /swl:*](COMANDOS.md): ciclo GSD, calidad, release, diagnóstico — fuente en `comandos/swl/`
-- [37 reglas base + 40 por lenguaje](INVENTARIO.md): políticas obligatorias por matcher — fuente en `reglas/`
-- [49 hooks](INVENTARIO.md): telemetría, validación, seguridad; zero-deps, escrituras atómicas — fuente en `hooks/`
-
-## Opcional
-
-- [CHANGELOG](CHANGELOG.md): historial de versiones
-- [Índice de ADRs](.planning/adrs/README.md): decisiones de arquitectura
-- [Variables de entorno](docs/variables-entorno.md): configuración opt-in
+# swl-ses (@saulwade/swl-ses)
+
+> Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo), distribuido como paquete npm y plugin de Claude Code. 61 agentes, 181 habilidades, 48 comandos, 37 reglas base y 49 hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión 2.6.1.
+
+Archivo generado por `node scripts/generar-inventario.js` — no editar a mano. Las cifras se sincronizan con INVENTARIO.md en cada regeneración.
+
+## Documentación
+
+- [README](README.md): overview público y quickstart
+- [Manual de uso](MANUAL_USO.md): manual operacional completo
+- [Comandos](COMANDOS.md): referencia detallada de cada comando `/swl:*`
+- [Agentes](AGENTS.md): catálogo de agentes con capacidades
+- [Inventario](INVENTARIO.md): conteos oficiales de todos los componentes
+- [Instalación](INSTALACION.md): instalación, perfiles y configuración
+- [Instrucciones del proyecto](CLAUDE.md): convenciones, stack y reglas
+
+## Componentes
+
+- [61 agentes especializados](AGENTS.md): orquestación, implementación por stack, revisión, calidad, diseño — fuente en `agentes/`
+- [181 habilidades cargables bajo demanda](INVENTARIO.md): conocimiento operacional con divulgación progresiva — fuente en `habilidades/`
+- [48 comandos /swl:*](COMANDOS.md): ciclo GSD, calidad, release, diagnóstico — fuente en `comandos/swl/`
+- [37 reglas base + 40 por lenguaje](INVENTARIO.md): políticas obligatorias por matcher — fuente en `reglas/`
+- [49 hooks](INVENTARIO.md): telemetría, validación, seguridad; zero-deps, escrituras atómicas — fuente en `hooks/`
+
+## Opcional
+
+- [CHANGELOG](CHANGELOG.md): historial de versiones
+- [Índice de ADRs](.planning/adrs/README.md): decisiones de arquitectura
+- [Variables de entorno](docs/variables-entorno.md): configuración opt-in