@saulwade/swl-ses 2.5.3 → 2.6.1

package/habilidades/tdd-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.2.3"
+version: "1.2.4"
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -73,18 +73,19 @@ def test_descuento_cliente_premium_es_15_porciento():
 #### Evidencia RED en telemetría (gate G2 — proyectos con SWL)
 
 El RED debe dejar rastro verificable (cierra F-TDD-6: "TDD declarativo sin
-evidencia"). En proyectos con `.planning/`, registrar la corrida en
-`hooks/lib/loop-telemetry.js` ANTES de pasar a GREEN:
+evidencia"). En proyectos con `.planning/`, registrar la corrida con el CLI
+(resuelve cross-scope; en el repo madre equivale a `hooks/lib/loop-telemetry.js`)
+ANTES de pasar a GREEN:
 
 ```bash
-# Una vez por fase/tarea — abre la corrida
-node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'tdd',direccion:'lower_is_better',config:{fase:'0N',tarea:'T-NN'}});console.log(r.dir)"
+# Una vez por fase/tarea — abre la corrida (imprime el dir)
+swl-ses loop-telemetry iniciar --tipo=tdd --direccion=lower_is_better --config='{"fase":"0N","tarea":"T-NN"}'
 
 # Al confirmar el RED — métrica = número de tests fallando, descripción = fallo exacto
-node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:0,metrica:N,delta:0,estado:'baseline',descripcion:'RED T-NN: <error textual del runner>'})"
+swl-ses loop-telemetry registrar --dir=<dir> --iteracion=0 --metrica=<N> --delta=0 --estado=baseline --descripcion="RED T-NN: <error textual del runner>"
 
 # Al llegar a GREEN
-node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:1,metrica:0,delta:-N,estado:'keep',descripcion:'GREEN T-NN: suite verde'})"
+swl-ses loop-telemetry registrar --dir=<dir> --iteracion=1 --metrica=0 --delta=-<N> --estado=keep --descripcion="GREEN T-NN: suite verde"
 ```
 
 `hooks/tdd-gate.js` (warn-only, ADR-0035) busca la fila RED en
@@ -339,6 +340,10 @@ pytest --cov=src/services --cov-fail-under=90
 
 ## Gotchas / Errores comunes no obvios
 
+**Fixtures que apuntan a archivos que el sistema muta en runtime se rompen solos — congelar el fixture, nunca el archivo vivo** [caso real swl-ses 2026-07-10]: los tests del ciclo autónomo copiaban `instintos/proyecto.yaml` y `perfil-usuario.yaml` REALES del repo como fixtures; horas después el bootstrap del motor los pobló (72 señales, campos nuevos) y 2 tests verdes reventaron sin que nadie tocara código de test. Causa: el fixture era un puntero al estado vivo, no una instantánea. Con cualquier sistema que auto-muta archivos (telemetría, motores de aprendizaje, caches regenerables), TODO archivo del repo es potencialmente mutable en runtime. Fix: congelar la instantánea de fábrica en `tests/**/fixtures/` (p. ej. `git show HEAD:ruta > tests/x/fixtures/archivo`) y apuntar los tests ahí; documentar en el path del fixture POR QUÉ está congelado. Señal de detección temprana: un test que falla sin diff en el código de test ni en el SUT.
+
+**`node:test` hereda `process.exitCode`: un caso que lo deja en 1 marca el ARCHIVO entero como fallido aunque todos los tests pasen** [caso real swl-ses 2026-07-10]: un test de CLI que ejercita la rama de error (`wrapper que setea process.exitCode = 1` y retorna null) deja el exit code sucio; node:test reporta `pass N / fail 0` por caso pero el archivo cierra con "test failed" y exit 1. Fix: el test que ejercita ramas de error de CLIs restaura `process.exitCode = 0` tras el assert. Patrón: `assert.equal(process.exitCode, 1); process.exitCode = 0;` — verifica el contrato Y limpia.
+
 **Tests que dependen de que N llamadas caigan en el MISMO segundo (IDs con timestamp, sufijos de colisión) son flaky por frontera de segundo — congelar el reloj**: si el SUT genera identificadores tipo `tipo-YYMMDD-HHMMSS` y el test llama 3 veces esperando sufijos de colisión `-2`/`-3`, cruzar el límite de segundo entre llamadas hace que la 3ª obtenga timestamp nuevo sin colisión — falla intermitente que puede tumbar un `npm publish` (caso real swl-ses 2026-07-03: `loop-telemetry`). Causa: el SUT toma el reloj de pared internamente; el test no controla el tiempo. Fix (Node): `t.mock.timers.enable({ apis: ['Date'], now: new Date('2026-01-01T12:00:00Z') })` de `node:test` — el equivalente a freezegun; se restaura solo al terminar el test. En Python: `freezegun.freeze_time`. NUNCA "reintentar el test" ni ampliar ventanas: congelar el reloj hace la colisión determinista por construcción.
 
 **El ciclo TDD se rompe cuando el test en fase RED pasa sin implementación porque la función ya existe con otro nombre en el módulo y Python la importa silenciosamente desde un namespace diferente**: escribir `from app.services import calcular_descuento` en el test cuando `calcular_descuento` ya existe en `app.utils` (importada en `__init__.py`) hace que el test pase en RED sin error, invalidando el ciclo. Causa: los imports con `from app.services import *` en `__init__.py` pueden re-exportar funciones de submódulos, haciendo que el test encuentre una implementación inesperada. Fix: verificar con `python -c "from app.services import calcular_descuento; print(calcular_descuento.__module__)"` que el símbolo viene del módulo correcto. Usar imports explícitos en los tests (`from app.services.descuentos import calcular_descuento`) en lugar de imports de paquete.

package/habilidades/validacion-ci-sistema/SKILL.md

@@ -30,7 +30,7 @@ validar y un score de componentes sería engañoso. El gate determinista vive en
 `/swl:status salud` (Paso 0):
 
 ```bash
-node scripts/lib/detectar-host-swl.js --json
+swl-ses detectar-host --json
 ```
 
 Si `esHost: false`, NO ejecutar este skill: reportar que `salud` no aplica y

package/hooks/agente-lifecycle.js

@@ -21,9 +21,10 @@
  */
 
 const { desdePayloadHook, emitirCompletado } = require('./lib/agent-backend');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const es = require('./lib/execution-state');
 
-const CWD = process.cwd();
+const CWD = raizProyecto(process.cwd());
 
 // ---------------------------------------------------------------------------
 // Entrypoint

package/hooks/aiisms-detector.js

@@ -34,6 +34,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const { spawnSync, randomUUID } = require('child_process');
 const crypto = require('crypto');
@@ -92,10 +93,18 @@ if (!fs.existsSync(filePath)) {
   process.exit(0);
 }
 
-// Ruta del detector (zero-deps, stdlib Python)
-const CWD = process.cwd();
-const detector = path.join(CWD, 'habilidades', 'estilo-sin-ai-isms', 'scripts', 'detectar_aiisms.py');
-if (!fs.existsSync(detector)) {
+// Ancla de DATOS (nudges, rutas relativas): raíz del proyecto.
+const CWD = raizProyecto(process.cwd());
+// El detector es EJECUTABLE de la distribución SWL: se resuelve SOLO desde
+// la ubicación instalada del hook (__dirname), NUNCA desde el árbol del
+// proyecto — un repo no confiable podría plantar el script (hallazgo
+// revisor-seguridad 2026-07-10, clase spawn/require-desde-raíz).
+const detector = [
+  path.join(__dirname, '..', 'habilidades', 'estilo-sin-ai-isms', 'scripts', 'detectar_aiisms.py'),       // repo madre
+  path.join(__dirname, '..', 'skills', 'estilo-sin-ai-isms', 'scripts', 'detectar_aiisms.py'),            // destino global (~/.claude/hooks ~ skills hermanos)
+  path.join(__dirname, '..', '.claude', 'skills', 'estilo-sin-ai-isms', 'scripts', 'detectar_aiisms.py'), // destino local (<proyecto>/hooks + <proyecto>/.claude/skills)
+].find(p => { try { return fs.existsSync(p); } catch (_) { return false; } });
+if (!detector) {
   process.exit(0);
 }
 

package/hooks/audit-trail.js

@@ -19,13 +19,14 @@
  */
 
 const fs    = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path  = require('path');
 const http  = require('http');
 const https = require('https');
 
 const { appendAudit: merkleAppend } = require(path.join(__dirname, 'lib', 'merkle-audit'));
 
-const CWD        = process.cwd();
+const CWD        = raizProyecto(process.cwd());
 const AUDIT_FILE = path.join(CWD, '.planning', 'audit.jsonl');
 const MERKLE_FILE = path.join(CWD, '.planning', 'audit-merkle.jsonl');
 

package/hooks/auto-consolidacion.js

@@ -29,6 +29,7 @@
  */
 
 const path = require('path');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const fs   = require('fs');
 const os   = require('os');
 
@@ -97,7 +98,7 @@ process.stdin.on('end', () => {
     // Anti-spam: solo ejecutar 1 vez por sesión
     if (alreadyRan()) return;
 
-    const baseDir = process.cwd();
+    const baseDir = raizProyecto(process.cwd());
 
     // Verificar las 3 gates
     const gates = checkAllGates(baseDir, {

package/hooks/captura-acciones-post.js

@@ -19,6 +19,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
@@ -142,7 +143,7 @@ if (!require.main || require.main === module) {
   process.stdin.on('end', () => {
     try {
       const data = JSON.parse(inputRaw);
-      procesarTurno(data, process.cwd());
+      procesarTurno(data, raizProyecto(process.cwd()));
     } catch (_) {
       /* silencioso */
     }

package/hooks/captura-acciones-session.js

@@ -20,6 +20,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
@@ -145,7 +146,7 @@ if (!require.main || require.main === module) {
   process.stdin.on('data', (c) => { inputRaw += c; });
   process.stdin.on('end', () => {
     try {
-      inspeccionar(process.cwd());
+      inspeccionar(raizProyecto(process.cwd()));
     } catch (_) {
       /* silencioso: el hook nunca bloquea la sesión */
     }

package/hooks/captura-feedback-usuario.js

@@ -25,6 +25,7 @@
  */
 
 const fs   = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 // ---------------------------------------------------------------------------
@@ -104,7 +105,7 @@ function detectarFeedback(prompt) {
  */
 function encolar(hallazgo, meta) {
   try {
-    const dir = path.join(process.cwd(), '.planning', 'evolution');
+    const dir = path.join(raizProyecto(process.cwd()), '.planning', 'evolution');
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
     const entrada = {
@@ -140,7 +141,7 @@ process.stdin.on('end', () => {
     if (hallazgos.length === 0) return;
 
     for (const h of hallazgos) {
-      encolar(h, { sessionId, cwd: process.cwd() });
+      encolar(h, { sessionId, cwd: raizProyecto(process.cwd()) });
     }
   } catch (_) { /* silencioso */ }
 });

package/hooks/claudemd-bloat-detector.js

@@ -36,6 +36,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const crypto = require('crypto');
 
@@ -93,9 +94,17 @@ if (!fs.existsSync(filePath)) {
 }
 
 // ─── Ejecutar auditor (módulo, no subproceso) ─────────────────────────────
-const CWD = process.cwd();
-const auditorPath = path.join(CWD, 'scripts', 'auditar-claudemd.js');
-if (!fs.existsSync(auditorPath)) {
+// Ancla de DATOS (nudges, rutas relativas): raíz del proyecto.
+const CWD = raizProyecto(process.cwd());
+// El auditor es MÓDULO de la distribución SWL: se resuelve SOLO desde la
+// ubicación instalada del hook (__dirname), NUNCA desde el árbol del
+// proyecto — un require() de un path plantado por un repo no confiable es
+// ejecución de código (hallazgo revisor-seguridad 2026-07-10).
+const auditorPath = [
+  path.join(__dirname, '..', 'scripts', 'auditar-claudemd.js'), // repo madre
+  path.join(__dirname, 'auditar-claudemd.js'),                  // destino aplanado
+].find(p => { try { return fs.existsSync(p); } catch (_) { return false; } });
+if (!auditorPath) {
   // No hay auditor instalado en este destino; salir silenciosamente
   process.exit(0);
 }

package/hooks/claudemd-duplicacion-detector.js

@@ -39,6 +39,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
@@ -102,9 +103,18 @@ if (!fs.existsSync(filePath)) {
 }
 
 // ─── Cargar detector ──────────────────────────────────────────────────────
-const CWD = process.cwd();
-const detectorPath = path.join(CWD, 'scripts', 'lib', 'detector-reglas-duplicadas.js');
-if (!fs.existsSync(detectorPath)) {
+// Ancla de DATOS (nudges, rutas relativas): raíz del proyecto.
+const CWD = raizProyecto(process.cwd());
+// El detector es MÓDULO de la distribución SWL: se resuelve SOLO desde la
+// ubicación instalada del hook (__dirname), NUNCA desde el árbol del
+// proyecto — un require() de un path plantado por un repo no confiable es
+// ejecución de código (hallazgo revisor-seguridad 2026-07-10).
+const detectorPath = [
+  path.join(__dirname, '..', 'scripts', 'lib', 'detector-reglas-duplicadas.js'), // repo madre
+  path.join(__dirname, 'lib', 'detector-reglas-duplicadas.js'),                  // destino (scripts/lib → hooks/lib)
+  path.join(__dirname, 'detector-reglas-duplicadas.js'),                         // destino legado aplanado
+].find(p => { try { return fs.existsSync(p); } catch (_) { return false; } });
+if (!detectorPath) {
   // No hay detector instalado en este destino; salir silenciosamente
   process.exit(0);
 }

package/hooks/contexto-iteracion.js

@@ -28,6 +28,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 const { atomicWriteJSON } = require('./lib/atomic-write');
@@ -112,7 +113,7 @@ function main() {
     try {
       if (process.env.SWL_CONTEXTO_ITERACION === '0') return;
 
-      const activa = corridaActiva(process.cwd(), { maxEdadMin: 30 });
+      const activa = corridaActiva(raizProyecto(process.cwd()), { maxEdadMin: 30 });
       if (!activa) return;
       if (!debeInyectar(activa.dir)) return;
 

package/hooks/contexto-subagente.js

@@ -1,68 +1,68 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: contexto-subagente.js
- * Tipo: SubagentStart (aplica a todos los subagentes Task/Agent)
- *
- * El contexto emitido por hooks de SessionStart es solo del hilo padre y
- * NUNCA llega a los subagentes: cada agente spawneado vía Task/Agent corre
- * sin las disciplinas activas de la sesión (patrón documentado en ponytail
- * issue #252 — mismo gap verificado en swl-ses el 2026-07-03: 0 usos de
- * SubagentStart hasta este hook).
- *
- * Re-inyecta a cada subagente un bloque compacto (~120 tokens) con las
- * disciplinas transversales no negociables: idioma es-MX, escalera de código
- * mínimo con guardas intocables, y la convención de marcador `simplificado:`.
- * Deliberadamente mínimo — el costo se paga en CADA spawn de subagente.
- *
- * Opt-out: SWL_CONTEXTO_SUBAGENTE=0 desactiva la inyección.
- * Formato de salida: SubagentStart requiere la forma JSON hookSpecificOutput
- * (stdout crudo se descarta en este evento — a diferencia de SessionStart).
- */
-
-/**
- * Construye el bloque de disciplinas que se inyecta al subagente.
- *
- * @returns {string} Contexto compacto en es-MX.
- */
-function construirContexto() {
-  return [
-    'DISCIPLINAS SWL ACTIVAS (heredadas de la sesión padre):',
-    '- Idioma: español de México en todo output (código, comentarios, commits, reportes).',
-    '- Código mínimo — escalera antes de escribir: ¿necesita existir (YAGNI)? →',
-    '  ¿ya existe en este codebase? → ¿stdlib? → ¿feature nativa de la plataforma? →',
-    '  ¿dependencia ya instalada? → ¿una línea? → solo entonces, el mínimo que funciona.',
-    '- Guardas intocables (nunca simplificar): validación en trust boundaries,',
-    '  manejo de errores que previene pérdida de datos, seguridad, accesibilidad.',
-    '- Simplificación deliberada se marca: `simplificado: <techo>, <trigger de upgrade>`.',
-    '- Bug fix = causa raíz: grep de todos los callers antes de parchar uno.',
-    'Detalle completo: Skill("prevencion-sobreingenieria").',
-  ].join('\n');
-}
-
-/**
- * Emite el contexto en el formato JSON que SubagentStart exige.
- * Nunca falla hacia afuera: un stdout roto no debe reportarse como hook error.
- */
-function main() {
-  if (process.env.SWL_CONTEXTO_SUBAGENTE === '0') return;
-  try {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'SubagentStart',
-        additionalContext: construirContexto(),
-      },
-    }));
-  } catch (_) {
-    // Silencioso — no interrumpir el spawn del subagente.
-  }
-}
-
-// Entrypoint directo o wrapper `node -e "require(...)"` (require.main undefined).
-// No consume stdin: emite y termina — sin listeners, el proceso sale solo.
-if (!require.main || require.main === module) {
-  main();
-}
-
-module.exports = { construirContexto };
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: contexto-subagente.js
+ * Tipo: SubagentStart (aplica a todos los subagentes Task/Agent)
+ *
+ * El contexto emitido por hooks de SessionStart es solo del hilo padre y
+ * NUNCA llega a los subagentes: cada agente spawneado vía Task/Agent corre
+ * sin las disciplinas activas de la sesión (patrón documentado en ponytail
+ * issue #252 — mismo gap verificado en swl-ses el 2026-07-03: 0 usos de
+ * SubagentStart hasta este hook).
+ *
+ * Re-inyecta a cada subagente un bloque compacto (~120 tokens) con las
+ * disciplinas transversales no negociables: idioma es-MX, escalera de código
+ * mínimo con guardas intocables, y la convención de marcador `simplificado:`.
+ * Deliberadamente mínimo — el costo se paga en CADA spawn de subagente.
+ *
+ * Opt-out: SWL_CONTEXTO_SUBAGENTE=0 desactiva la inyección.
+ * Formato de salida: SubagentStart requiere la forma JSON hookSpecificOutput
+ * (stdout crudo se descarta en este evento — a diferencia de SessionStart).
+ */
+
+/**
+ * Construye el bloque de disciplinas que se inyecta al subagente.
+ *
+ * @returns {string} Contexto compacto en es-MX.
+ */
+function construirContexto() {
+  return [
+    'DISCIPLINAS SWL ACTIVAS (heredadas de la sesión padre):',
+    '- Idioma: español de México en todo output (código, comentarios, commits, reportes).',
+    '- Código mínimo — escalera antes de escribir: ¿necesita existir (YAGNI)? →',
+    '  ¿ya existe en este codebase? → ¿stdlib? → ¿feature nativa de la plataforma? →',
+    '  ¿dependencia ya instalada? → ¿una línea? → solo entonces, el mínimo que funciona.',
+    '- Guardas intocables (nunca simplificar): validación en trust boundaries,',
+    '  manejo de errores que previene pérdida de datos, seguridad, accesibilidad.',
+    '- Simplificación deliberada se marca: `simplificado: <techo>, <trigger de upgrade>`.',
+    '- Bug fix = causa raíz: grep de todos los callers antes de parchar uno.',
+    'Detalle completo: Skill("prevencion-sobreingenieria").',
+  ].join('\n');
+}
+
+/**
+ * Emite el contexto en el formato JSON que SubagentStart exige.
+ * Nunca falla hacia afuera: un stdout roto no debe reportarse como hook error.
+ */
+function main() {
+  if (process.env.SWL_CONTEXTO_SUBAGENTE === '0') return;
+  try {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SubagentStart',
+        additionalContext: construirContexto(),
+      },
+    }));
+  } catch (_) {
+    // Silencioso — no interrumpir el spawn del subagente.
+  }
+}
+
+// Entrypoint directo o wrapper `node -e "require(...)"` (require.main undefined).
+// No consume stdin: emite y termina — sin listeners, el proceso sale solo.
+if (!require.main || require.main === module) {
+  main();
+}
+
+module.exports = { construirContexto };

package/hooks/degradacion-instintos.js

@@ -20,6 +20,7 @@
  */
 
 const fs   = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 const { atomicWriteSync } = require('./lib/atomic-write');
@@ -28,7 +29,7 @@ const { atomicWriteSync } = require('./lib/atomic-write');
 // Constantes
 // ---------------------------------------------------------------------------
 
-const RUTA_APRENDIZAJES = path.join(process.cwd(), '.planning', 'APRENDIZAJES.md');
+const RUTA_APRENDIZAJES = path.join(raizProyecto(process.cwd()), '.planning', 'APRENDIZAJES.md');
 const MAX_CONTRADICCIONES = 3;
 
 // Palabras clave que indican exito en el output del agente