@saulwade/swl-ses 2.2.4 → 2.3.0

package/hooks/lib/captura-acciones.js

@@ -0,0 +1,392 @@
+'use strict';
+
+/**
+ * Lib: captura-acciones.js
+ *
+ * Núcleo puro y testeable de la captura de SEÑALES DE ACCIÓN del usuario
+ * (Fase 17, "Aprendizaje de señales de usuario"). Mientras
+ * `captura-feedback-usuario.js` captura las señales VERBALES (palabras tecleadas
+ * en UserPromptSubmit), esta lib alimenta las señales de ACCIÓN — la mitad
+ * procedural que hoy se pierde:
+ *   - revert/reset de commits hechos por el agente,
+ *   - edición manual de archivos que el agente escribió,
+ *   - rechazo de un PLAN propuesto,
+ *   - override de un veredicto de /swl:verificar.
+ *
+ * Las señales se encolan en el MISMO `.planning/evolution/feedback-queue.jsonl`
+ * con `tipo:"accion"` (esquema extendido backward-compatible con las verbales),
+ * para el mismo consumidor (perfilador-usuario-swl + ciclo AGP). Alcance Fase 17:
+ * **solo capturar + telemetría** — sin conversión a memoria procedural.
+ *
+ * Consumida por los hooks `captura-acciones-post.js` (PostToolUse) y
+ * `captura-acciones-session.js` (SessionStart). Zero-deps salvo `atomic-write`
+ * (sibling en hooks/lib/). Todas las funciones son puras o reciben `baseDir`
+ * explícito → testeables en aislamiento.
+ *
+ * Opt-out unificado (en los hooks, no aquí): SWL_CAPTURAR_FEEDBACK=0.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// atomic-write es sibling en hooks/lib/ (y queda en el mismo dir tras el
+// aplanado del instalador). Fallback inline si faltara.
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./atomic-write'));
+} catch (_) {
+  atomicWriteJSON = (p, obj) => fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Sanitización de evidencia (REQ-17-07)
+//
+// Port de los 5 patrones de `registro-turnos.js:67-82` + `reglas/seguridad.md
+// § Sanitización PII centralizada`. La sanitización vive en el punto de
+// persistencia (encolarAccion) — ningún path de encolado puede omitirla.
+// ---------------------------------------------------------------------------
+
+const PATRONES_REDACT = [
+  /\b[A-Za-z0-9_-]{32,}\b/g, // tokens largos
+  /(?:sk|pk|key|token|secret|password|pwd|api[_-]?key)["':\s=]+[A-Za-z0-9_\-./]{8,}/gi,
+  /\bey[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\b/g, // JWT
+  /https?:\/\/[^:]+:[^@\s]+@/g, // basic auth en URL
+  /-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g, // PEM blocks
+];
+
+/** Redacta secretos de un texto libre (REQ-17-07). Best-effort, no lanza. */
+function sanitizarEvidencia(texto) {
+  if (!texto) return '';
+  let r = String(texto);
+  for (const re of PATRONES_REDACT) r = r.replace(re, '[REDACTED]');
+  return r;
+}
+
+/** SHA-256 hex de un string (módulo nativo, sin deps). */
+function hashContenido(str) {
+  return crypto.createHash('sha256').update(String(str == null ? '' : str)).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Rutas runtime (gitignored)
+// ---------------------------------------------------------------------------
+
+const MAX_EVIDENCIA_LEN = 500;
+
+function rutaCola(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'feedback-queue.jsonl');
+}
+function rutaIndiceWrites(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'agent-writes-index.json');
+}
+function rutaCommits(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'agent-commits.jsonl');
+}
+
+function asegurarEvolutionDir(baseDir) {
+  const dir = path.join(baseDir, '.planning', 'evolution');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// Encolado (REQ-17-06, REQ-17-07)
+// ---------------------------------------------------------------------------
+
+/**
+ * Encola una señal de acción en feedback-queue.jsonl. Esquema extendido
+ * backward-compatible: las entradas verbales legacy (sin `accion`) siguen
+ * parseando. La `evidencia` se sanitiza SIEMPRE aquí (invariante REQ-17-07).
+ *
+ * @param {string} baseDir  raíz del proyecto (cwd del hook).
+ * @param {object} accion   { accion, archivo?, evidencia?, sessionId?, cwd? }.
+ */
+function encolarAccion(baseDir, accion) {
+  try {
+    asegurarEvolutionDir(baseDir);
+    const entrada = {
+      ts: new Date().toISOString(),
+      sessionId: String(accion.sessionId || 'default'),
+      tipo: 'accion',
+      accion: accion.accion,
+      cwd: accion.cwd || baseDir,
+      procesado: false,
+    };
+    if (accion.archivo) entrada.archivo = String(accion.archivo);
+    if (accion.evidencia != null) {
+      entrada.evidencia = sanitizarEvidencia(accion.evidencia).slice(0, MAX_EVIDENCIA_LEN);
+    }
+    fs.appendFileSync(rutaCola(baseDir), JSON.stringify(entrada) + '\n');
+  } catch (_) {
+    /* nunca bloquear */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Índice de escrituras del agente (REQ-17-02, REQ-17-03)
+// ---------------------------------------------------------------------------
+
+/** Lee el índice de hashes de escritura del agente; {} si ausente/corrupto. */
+function leerIndiceWrites(baseDir) {
+  try {
+    const p = rutaIndiceWrites(baseDir);
+    if (!fs.existsSync(p)) return {};
+    const obj = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return obj && typeof obj === 'object' ? obj : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+function escribirIndiceWrites(baseDir, indice) {
+  try {
+    asegurarEvolutionDir(baseDir);
+    atomicWriteJSON(rutaIndiceWrites(baseDir), indice);
+  } catch (_) {
+    /* best-effort */
+  }
+}
+
+/** Registra el hash del último write del agente sobre `rutaRel`. */
+function registrarEscrituraAgente(baseDir, rutaRel, contenido, meta = {}) {
+  const indice = leerIndiceWrites(baseDir);
+  indice[rutaRel] = {
+    sha256: hashContenido(contenido),
+    ts: new Date().toISOString(),
+    sessionId: String(meta.sessionId || 'default'),
+  };
+  escribirIndiceWrites(baseDir, indice);
+  return indice;
+}
+
+// ---------------------------------------------------------------------------
+// Registro de commits del agente (REQ-17-01) — sin co-author (git-coauthor.md)
+// ---------------------------------------------------------------------------
+
+/** Registra un SHA commiteado por el agente en agent-commits.jsonl. */
+function registrarCommitAgente(baseDir, { sessionId, sha, mensaje } = {}) {
+  try {
+    if (!sha) return;
+    asegurarEvolutionDir(baseDir);
+    const entrada = { ts: new Date().toISOString(), sessionId: String(sessionId || 'default'), sha: String(sha) };
+    // `mensaje` también se sanitiza (un mensaje de commit puede llevar un token
+    // pegado): este es un segundo path de persistencia y la invariante de no
+    // filtrar secretos aplica a TODO path, no solo a encolarAccion (sec BAJA-1).
+    if (mensaje) entrada.mensaje = sanitizarEvidencia(String(mensaje)).slice(0, 200);
+    fs.appendFileSync(rutaCommits(baseDir), JSON.stringify(entrada) + '\n');
+  } catch (_) {
+    /* best-effort */
+  }
+}
+
+/** Lee los SHAs registrados por el agente; [] si ausente/corrupto. */
+function leerCommitsAgente(baseDir) {
+  try {
+    const p = rutaCommits(baseDir);
+    if (!fs.existsSync(p)) return [];
+    return fs
+      .readFileSync(p, 'utf8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch (_) {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detectores puros
+// ---------------------------------------------------------------------------
+
+/**
+ * SHAs registrados por el agente que ya NO están en el historial actual
+ * (revert/reset). REQ-17-01.
+ * @param {Array<{sha:string}>|string[]} commitsRegistrados
+ * @param {string[]} shasHistorialActual
+ * @returns {string[]}
+ */
+function detectarRevert(commitsRegistrados, shasHistorialActual) {
+  const hist = new Set(shasHistorialActual || []);
+  const vistos = new Set();
+  const out = [];
+  for (const c of commitsRegistrados || []) {
+    const sha = typeof c === 'string' ? c : c && c.sha;
+    if (!sha || vistos.has(sha)) continue;
+    vistos.add(sha);
+    if (!hist.has(sha)) out.push(sha);
+  }
+  return out;
+}
+
+/**
+ * Archivos cuyo hash en disco difiere del último write del agente (edición
+ * neta del usuario fuera de sesión). REQ-17-02.
+ * @param {Object} indiceWrites  { ruta: { sha256 } }
+ * @param {Object} hashActualPorArchivo  { ruta: sha256 }
+ * @returns {string[]}
+ */
+function detectarEdicionNeta(indiceWrites, hashActualPorArchivo) {
+  const out = [];
+  for (const ruta of Object.keys(indiceWrites || {})) {
+    const actual = hashActualPorArchivo ? hashActualPorArchivo[ruta] : undefined;
+    if (actual === undefined) continue; // archivo borrado/ilegible → no inferir
+    const registrado = indiceWrites[ruta] && indiceWrites[ruta].sha256;
+    if (registrado && actual !== registrado) out.push(ruta);
+  }
+  return out;
+}
+
+/**
+ * true si el contenido re-leído difiere del último write del agente (edición
+ * manual en caliente). false si coincide o no hay registro. REQ-17-03.
+ */
+function detectarEdicionManual(rutaArchivo, contenidoReleido, indiceWrites) {
+  const rec = indiceWrites && indiceWrites[rutaArchivo];
+  if (!rec || !rec.sha256) return false;
+  return hashContenido(contenidoReleido) !== rec.sha256;
+}
+
+function _frontmatterCampo(contenido, campo) {
+  const m = contenido.match(new RegExp(`^${campo}:\\s*(.+)$`, 'm'));
+  return m ? m[1].trim() : null;
+}
+
+function _faseDeNombre(nombre) {
+  const m = nombre.match(/^(\d{1,3})-/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * PLANs que parecen rechazados: estado `rechazado` explícito, o estado
+ * `borrador` sin lock G1 mientras la fase ya cerró (existe NN-RESUMEN.md).
+ * REQ-17-04.
+ * @returns {Array<{fase:number, archivo:string}>}
+ */
+function _evaluarPlanRechazado(archivo, fasesDir, locksDir) {
+  let contenido = '';
+  try {
+    contenido = fs.readFileSync(path.join(fasesDir, archivo), 'utf8');
+  } catch (_) {
+    return null;
+  }
+  const estado = (_frontmatterCampo(contenido, 'estado') || '').toLowerCase();
+  const fase = _faseDeNombre(archivo);
+  if (estado === 'rechazado') return { fase, archivo };
+  if (estado === 'borrador') {
+    const lock = path.join(locksDir, archivo + '.lock');
+    const resumen = path.join(fasesDir, archivo.replace('-PLAN.md', '-RESUMEN.md'));
+    if (!fs.existsSync(lock) && fs.existsSync(resumen)) return { fase, archivo };
+  }
+  return null;
+}
+
+function detectarPlanRechazado(baseDir) {
+  const fasesDir = path.join(baseDir, '.planning', 'fases');
+  const locksDir = path.join(baseDir, '.planning', 'locks');
+  let archivos;
+  try {
+    archivos = fs.readdirSync(fasesDir).filter((f) => /-PLAN\.md$/.test(f));
+  } catch (_) {
+    return [];
+  }
+  return archivos.map((a) => _evaluarPlanRechazado(a, fasesDir, locksDir)).filter(Boolean);
+}
+
+/**
+ * VERIFICACIONes con veredicto no-aprobatorio (caso determinista de override).
+ * La inferencia "se procedió igual" queda como inspección (T-10). REQ-17-05.
+ * @returns {Array<{fase:number, archivo:string, veredicto:string}>}
+ */
+function detectarVeredictoOverride(baseDir) {
+  const out = [];
+  const fasesDir = path.join(baseDir, '.planning', 'fases');
+  let archivos;
+  try {
+    archivos = fs.readdirSync(fasesDir).filter((f) => /-VERIFICACION\.md$/.test(f));
+  } catch (_) {
+    return out;
+  }
+  for (const archivo of archivos) {
+    let contenido = '';
+    try {
+      contenido = fs.readFileSync(path.join(fasesDir, archivo), 'utf8');
+    } catch (_) {
+      continue;
+    }
+    const m = contenido.match(/VEREDICTO:?\s*(RECHAZADO|REQUIERE[_\s]CORRECCIONES)/i);
+    if (m) out.push({ fase: _faseDeNombre(archivo), archivo, veredicto: m[1].toUpperCase().replace(/\s/g, '_') });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Telemetría (REQ-17-09)
+// ---------------------------------------------------------------------------
+
+const SUBTIPOS = ['revert', 'edicion-manual', 'plan-rechazado', 'veredicto-override'];
+
+/** Conteo por subtipo de acción en la cola; ignora entradas verbales. */
+function contarPorSubtipo(baseDir) {
+  const conteo = Object.fromEntries(SUBTIPOS.map((s) => [s, 0]));
+  try {
+    const p = rutaCola(baseDir);
+    if (!fs.existsSync(p)) return conteo;
+    for (const linea of fs.readFileSync(p, 'utf8').split(/\r?\n/)) {
+      if (!linea) continue;
+      let e;
+      try {
+        e = JSON.parse(linea);
+      } catch (_) {
+        continue;
+      }
+      if (e && e.tipo === 'accion' && Object.prototype.hasOwnProperty.call(conteo, e.accion)) {
+        conteo[e.accion] += 1;
+      }
+    }
+  } catch (_) {
+    /* devuelve ceros */
+  }
+  return conteo;
+}
+
+module.exports = {
+  sanitizarEvidencia,
+  hashContenido,
+  encolarAccion,
+  leerIndiceWrites,
+  escribirIndiceWrites,
+  registrarEscrituraAgente,
+  registrarCommitAgente,
+  leerCommitsAgente,
+  detectarRevert,
+  detectarEdicionNeta,
+  detectarEdicionManual,
+  detectarPlanRechazado,
+  detectarVeredictoOverride,
+  contarPorSubtipo,
+  SUBTIPOS,
+  MAX_EVIDENCIA_LEN,
+  _internals: { PATRONES_REDACT, rutaCola, rutaIndiceWrites, rutaCommits },
+};
+
+// ---------------------------------------------------------------------------
+// CLI: `node hooks/lib/captura-acciones.js --conteo` (REQ-17-09 consultable)
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  try {
+    if (process.argv.includes('--conteo')) {
+      process.stdout.write(JSON.stringify(contarPorSubtipo(process.cwd()), null, 2) + '\n');
+    }
+  } catch (_) {
+    /* exit 0 siempre */
+  }
+}

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. 60 agentes, 182 habilidades, 44 comandos, 37 reglas base y 48 hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión 2.2.4.
-
-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
-
-- 60 agentes especializados en `agentes/` (orquestación, implementación por stack, revisión, calidad, diseño)
-- 182 habilidades cargables bajo demanda en `habilidades/` (conocimiento operacional con divulgación progresiva)
-- 44 comandos `/swl:*` en `comandos/swl/` (ciclo GSD, calidad, release, diagnóstico)
-- 37 reglas base + 40 reglas por lenguaje en `reglas/` (políticas obligatorias por matcher)
-- 48 hooks en `hooks/` (telemetría, validación, seguridad; zero-deps, escrituras atómicas)
-
-## 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. 60 agentes, 182 habilidades, 44 comandos, 37 reglas base y 50 hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión 2.3.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
+
+- 60 agentes especializados en `agentes/` (orquestación, implementación por stack, revisión, calidad, diseño)
+- 182 habilidades cargables bajo demanda en `habilidades/` (conocimiento operacional con divulgación progresiva)
+- 44 comandos `/swl:*` en `comandos/swl/` (ciclo GSD, calidad, release, diagnóstico)
+- 37 reglas base + 40 reglas por lenguaje en `reglas/` (políticas obligatorias por matcher)
+- 50 hooks en `hooks/` (telemetría, validación, seguridad; zero-deps, escrituras atómicas)
+
+## 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