@saulwade/swl-ses 1.9.0 → 2.1.0

package/hooks/lib/evolution-tracker.js

@@ -64,6 +64,7 @@ const EXCLUDED_FILENAME_PATTERNS = [
   /\.rej$/,             // patch reject
   /\.merge_file_/,      // merge tools (kdiff3, etc.)
   /~$/,                 // editores tipo Emacs/Vim
+  /\.evolved-diff\.(md|txt)$/, // diffs de merge (no son componentes; .md legacy)
 ];
 
 /**
@@ -407,7 +408,13 @@ const DIFF_NOISY_THRESHOLD = 50;
  *
  * Estrategia: toma el archivo nuevo como base y re-aplica los campos de
  * evolución (frontmatter evolved-*). Las mutaciones de contenido se preservan
- * generando un archivo .evolved-diff.md que Claude puede re-aplicar.
+ * generando un archivo `.evolved-diff.txt` que Claude puede re-aplicar.
+ *
+ * Extensión `.txt` (no `.md`) deliberada: el diff vive junto al componente
+ * evolucionado (incluyendo `commands/`), pero el harness de Claude Code indexa
+ * todo `.md` dentro de `commands/` como slash-command — un `aprender.evolved-diff.md`
+ * aparecería como `/swl:aprender.evolved-diff`. Con `.txt` el harness no lo indexa
+ * y `scanEvolved` (que solo recorre `.md`) tampoco lo confunde con un componente.
  *
  * Comparación: solo el body (post-frontmatter) se compara línea-a-línea.
  * El frontmatter SIEMPRE diverge (el destino tiene campos `evolved-*` que el
@@ -415,7 +422,8 @@ const DIFF_NOISY_THRESHOLD = 50;
  * contarlo como mutación genera ruido por desplazamiento.
  *
  * Limpieza: cuando un merge posterior elimina la divergencia (diffs vacíos),
- * borra el `.evolved-diff.md` huérfano de sesiones previas si existe.
+ * borra el `.evolved-diff.txt` huérfano de sesiones previas si existe (y el
+ * `.evolved-diff.md` legacy de versiones anteriores a esta corrección).
  *
  * Cap defensivo: si tras alinear correctamente el body aún hay más de
  * `DIFF_NOISY_THRESHOLD` líneas distintas, genera un resumen estadístico
@@ -470,7 +478,17 @@ function mergeEvolved(destino, origen, versionNueva) {
       }
     }
 
-    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
+    const diffPath = destino.replace(/\.md$/, '.evolved-diff.txt');
+    // Legacy: versiones previas escribían el diff como `.evolved-diff.md`, que
+    // el harness indexaba como slash-command. Se limpia siempre que se toca el
+    // componente, exista o no divergencia nueva.
+    const diffPathLegacy = destino.replace(/\.md$/, '.evolved-diff.md');
+    const limpiarLegacy = () => {
+      if (fs.existsSync(diffPathLegacy)) {
+        try { fs.unlinkSync(diffPathLegacy); return true; } catch { /* best-effort */ }
+      }
+      return false;
+    };
 
     if (diffs.length === 0) {
       // Sin diferencias reales — limpiar diff huérfano si existe (de sesión
@@ -486,6 +504,7 @@ function mergeEvolved(destino, origen, versionNueva) {
           // el merge sigue siendo válido.
         }
       }
+      if (limpiarLegacy()) cleanedDiff = true;
 
       // force: true — `mergeEvolved` solo se invoca en contexto de update
       // intencional. El skip de isPackageRoot() aplica a la primera marca
@@ -557,6 +576,8 @@ function mergeEvolved(destino, origen, versionNueva) {
     ].join('\n');
 
     atomicWriteSync(diffPath, diffContent, 'utf8');
+    // Si existía el `.evolved-diff.md` legacy, eliminarlo: el `.txt` lo reemplaza.
+    limpiarLegacy();
 
     return { merged: true, diffPath, diffsCount: diffs.length, truncated };
   } catch (err) {

package/hooks/lib/propose-step.js

@@ -0,0 +1,357 @@
+'use strict';
+
+/**
+ * hooks/lib/propose-step.js — Fase 13 (ADR-0037): propose-step de adyacencias.
+ *
+ * Separa PROPONER de ACTUAR: al cerrar una tarea/fase, evalúa el diff contra una
+ * checklist mecanizable de adyacencias de riesgo y emite un anexo PROPOSITIVO.
+ * Nunca bloquea, nunca ejecuta. El anexo es texto; el usuario decide si actúa.
+ *
+ * Taxonomía v1 (D-13-01): 2 señales de alta precisión.
+ *   - auth-pii-pagos:  el cambio toca autenticación, PII o pagos.
+ *   - migracion-schema: el cambio introduce o modifica el esquema de datos.
+ *
+ * Telemetría de aceptación en archivo separado .planning/user-profile/
+ * propose-telemetria.json, reusando la lógica pura de hooks/lib/briefing.js
+ * (D-13-07). Opt-out con SWL_PROPOSE=0.
+ *
+ * Zero-deps (Node stdlib). Require dual ./lib/X → ./X para funcionar tanto en el
+ * repo madre como en el destino aplanado por el instalador (patrón D-17 de F12).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// ─── require dual (repo madre: ./lib/X ; destino aplanado: ./X) ──────────────
+
+function requireDual(nombre) {
+  try {
+    return require(`./${nombre}`); // repo madre (mismo dir) o destino aplanado
+  } catch (e1) {
+    if (e1 && e1.code !== 'MODULE_NOT_FOUND') throw e1;
+    return require(`./lib/${nombre}`);
+  }
+}
+
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = requireDual('atomic-write'));
+} catch (_) {
+  // Fallback no-atómico: funciona, pierde la garantía de write atómico.
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
+let briefing;
+try {
+  briefing = requireDual('briefing');
+} catch (_) {
+  briefing = null; // sin telemetría compartida; la detección sigue funcionando
+}
+
+// ─── detectores de señales ───────────────────────────────────────────────────
+
+// Patrones de auth/PII/pagos. Acotados a alta precisión: word boundaries donde
+// el término es ambiguo (rfc, card, cvv, pago) para no disparar con prosa.
+const RE_AUTH_PII_DIFF = new RegExp(
+  [
+    'password', 'passwd', 'contraseña',
+    '\\btoken\\b', 'secret', 'api[_-]?key', '\\bjwt\\b', 'oauth',
+    'authorization', '\\bbearer\\b', '\\bcredential', '\\bsession\\b',
+    'stripe', 'payment', '\\bpago\\b', '\\bpagos\\b', 'tarjeta',
+    '\\bcvv\\b', '\\bcard\\b', '\\bcurp\\b', '\\brfc\\b',
+  ].join('|'),
+  'i',
+);
+
+const RE_AUTH_PII_PATH = new RegExp(
+  '(^|/)(auth|login|logout|oauth|jwt|session|credential|credentials|password|payment|pagos?|stripe|checkout)([/._-]|$)',
+  'i',
+);
+
+// Patrones de migración / esquema de datos.
+const RE_SCHEMA_PATH = new RegExp(
+  '(^|/)(migrations?|alembic|models?|schema|prisma)([/._-]|$)|\\.sql$|schema\\.prisma$',
+  'i',
+);
+
+const RE_SCHEMA_DIFF = new RegExp(
+  [
+    '\\bALTER\\s+TABLE\\b', '\\bCREATE\\s+TABLE\\b', '\\bDROP\\s+TABLE\\b',
+    '\\bADD\\s+COLUMN\\b', '\\bDROP\\s+COLUMN\\b', '\\bRENAME\\s+(TABLE|COLUMN)\\b',
+    'op\\.(create_table|add_column|drop_column|alter_column)',
+    'createTable|addColumn|dropColumn', // ORMs JS (knex, sequelize)
+  ].join('|'),
+  'i',
+);
+
+function _primerPathQueMatchea(paths, re) {
+  if (!Array.isArray(paths)) return null;
+  for (const p of paths) {
+    if (typeof p === 'string' && re.test(p)) return p;
+  }
+  return null;
+}
+
+// Cota de tamaño del diff antes de aplicar regex: acota ReDoS y memoria. El
+// detector solo necesita el primer match, así que 2 MiB son más que suficientes.
+const MAX_DIFF_SCAN = 2 * 1024 * 1024;
+
+// Devuelve SOLO si el diff matchea (boolean), nunca el fragmento matcheado: la
+// evidencia del anexo NO debe contener slices del diff (podrían arrastrar el
+// secreto adyacente al keyword). Hardening por construcción.
+function _diffMatchea(diff, re) {
+  if (typeof diff !== 'string') return false;
+  return re.test(diff.length > MAX_DIFF_SCAN ? diff.slice(0, MAX_DIFF_SCAN) : diff);
+}
+
+/**
+ * Detecta si el cambio toca autenticación, PII o pagos.
+ * @param {string[]} paths - rutas de archivos del diff.
+ * @param {string} diff - contenido del diff.
+ * @returns {null|{categoria,titulo,evidencia,accion}}
+ */
+function detectarAuthPiiPagos(paths, diff) {
+  const porPath = _primerPathQueMatchea(paths, RE_AUTH_PII_PATH);
+  const porDiff = porPath ? false : _diffMatchea(diff, RE_AUTH_PII_DIFF);
+  if (!porPath && !porDiff) return null;
+  return {
+    categoria: 'auth-pii-pagos',
+    titulo: 'El cambio toca autenticación, PII o pagos',
+    evidencia: porPath ? `path: ${porPath}` : 'patrón detectado en el diff',
+    accion:
+      'Confirma revisión de seguridad (revisor-seguridad-swl) y tests de ' +
+      'autorización/validación antes de cerrar; no expongas secretos en logs.',
+  };
+}
+
+/**
+ * Detecta si el cambio introduce o modifica el esquema de datos.
+ * @param {string[]} paths
+ * @param {string} diff
+ * @returns {null|{categoria,titulo,evidencia,accion}}
+ */
+function detectarMigracionSchema(paths, diff) {
+  const porPath = _primerPathQueMatchea(paths, RE_SCHEMA_PATH);
+  const porDiff = porPath ? false : _diffMatchea(diff, RE_SCHEMA_DIFF);
+  if (!porPath && !porDiff) return null;
+  return {
+    categoria: 'migracion-schema',
+    titulo: 'El cambio introduce o modifica el esquema de datos',
+    evidencia: porPath ? `path: ${porPath}` : 'patrón detectado en el diff',
+    accion:
+      'Confirma plan de rollback / expand-contract y reversibilidad de la ' +
+      'migración (migrador-swl); verifica que no rompe datos existentes.',
+  };
+}
+
+const DETECTORES = [detectarAuthPiiPagos, detectarMigracionSchema];
+
+/**
+ * Evalúa todas las señales sobre un diff. Función pura: solo datos, sin side
+ * effects (REQ-13-04).
+ * @param {string[]} paths
+ * @param {string} diff
+ * @returns {{señales: Array<{categoria,titulo,evidencia,accion}>}}
+ */
+function evaluarSenales(paths, diff) {
+  const señales = [];
+  for (const detectar of DETECTORES) {
+    const s = detectar(paths, diff);
+    if (s) señales.push(s);
+  }
+  return { señales };
+}
+
+// ─── anexo propositivo ───────────────────────────────────────────────────────
+
+/**
+ * Formatea el anexo propositivo. Devuelve null si no hay señales activas (silencio
+ * total, D-13-03) o si todas las categorías están silenciadas.
+ * @param {Array} señales
+ * @param {Set<string>} silenciadas - categorías que la telemetría silenció.
+ * @returns {string|null}
+ */
+function formatearAnexo(señales, silenciadas) {
+  const sil = silenciadas instanceof Set ? silenciadas : new Set();
+  const activas = Array.isArray(señales) ? señales.filter((s) => s && !sil.has(s.categoria)) : [];
+  if (activas.length === 0) return null;
+  const lineas = [
+    '## Anexo propositivo — adyacencias de riesgo',
+    '',
+    'Sugerencias, **no acciones**: nada se ejecuta ni se bloquea automáticamente. ' +
+      'Revisa si aplican.',
+    '',
+  ];
+  for (const s of activas) {
+    lineas.push(`- [${s.categoria}] ${s.titulo} (${s.evidencia}) → ${s.accion}`);
+  }
+  return lineas.join('\n');
+}
+
+// ─── telemetría de aceptación (archivo separado, REQ-13-08/09) ───────────────
+//
+// Modelo a nivel de CATEGORÍA (no por hash). Las señales del propose tienen
+// título fijo por categoría → el conteo por-hash de briefing.actualizarTelemetria
+// nunca alcanzaría MIN_MUESTRAS_SILENCIO. Se reusan los UMBRALES de briefing.js
+// (D-13-07) y categoriasSilenciadas, pero el conteo es por exposición:
+//   - registrarPropose: mostrado += 1 por categoría mostrada (automático).
+//   - registrarFeedback: actuado/ignorado += 1 (canal de aceptación explícito).
+//   - silenciada se recomputa con los mismos umbrales que el briefing.
+
+const TELE_PATH = ['.planning', 'user-profile', 'propose-telemetria.json'];
+
+// Umbrales: reusar los de briefing.js; fallback a los mismos valores si la lib
+// no está disponible en el destino.
+const UMBRAL = {
+  RATIO_SILENCIO: (briefing && briefing.RATIO_SILENCIO) || 0.8,
+  MIN_MUESTRAS_SILENCIO: (briefing && briefing.MIN_MUESTRAS_SILENCIO) || 5,
+};
+
+function telemetriaPath(baseDir) {
+  return path.join(baseDir || process.cwd(), ...TELE_PATH);
+}
+
+function _catVacia() {
+  return { mostrado: 0, actuado: 0, ignorado: 0, silenciada: false, ultima_ts: null };
+}
+
+/** Lee la telemetría de propose; fallback a estructura vacía. */
+function leerTelemetriaPropose(baseDir) {
+  try {
+    const raw = fs.readFileSync(telemetriaPath(baseDir), 'utf8');
+    const obj = JSON.parse(raw);
+    return { categorias: obj.categorias && typeof obj.categorias === 'object' ? obj.categorias : {} };
+  } catch (_) {
+    return { categorias: {} };
+  }
+}
+
+/** Recalcula silenciada con los umbrales del briefing. Muta la categoría dada. */
+function _recomputarSilenciada(c) {
+  c.silenciada =
+    c.mostrado >= UMBRAL.MIN_MUESTRAS_SILENCIO &&
+    c.ignorado / c.mostrado >= UMBRAL.RATIO_SILENCIO;
+  return c;
+}
+
+function _persistir(baseDir, tele) {
+  try {
+    const dir = path.dirname(telemetriaPath(baseDir));
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    atomicWriteJSON(telemetriaPath(baseDir), tele);
+  } catch (_) {
+    // persistir es best-effort; no romper el cierre de la tarea.
+  }
+}
+
+/**
+ * Registra la exposición de un anexo: mostrado += 1 por cada categoría presente.
+ * @param {string} baseDir
+ * @param {Array} señales
+ * @param {string} hoyISO - timestamp inyectable para tests deterministas.
+ * @returns {{categorias}}
+ */
+function registrarPropose(baseDir, señales, hoyISO) {
+  const tele = leerTelemetriaPropose(baseDir);
+  const hoy = hoyISO || new Date().toISOString();
+  for (const s of Array.isArray(señales) ? señales : []) {
+    if (!s || !s.categoria) continue;
+    const c = tele.categorias[s.categoria] || _catVacia();
+    c.mostrado += 1;
+    c.ultima_ts = hoy;
+    _recomputarSilenciada(c);
+    tele.categorias[s.categoria] = c;
+  }
+  _persistir(baseDir, tele);
+  return tele;
+}
+
+/**
+ * Registra feedback de aceptación de una categoría (canal explícito).
+ * @param {string} baseDir
+ * @param {string} categoria
+ * @param {'actuado'|'ignorado'} tipo
+ * @param {string} hoyISO
+ * @returns {{categorias}}
+ */
+function registrarFeedback(baseDir, categoria, tipo, hoyISO) {
+  if (tipo !== 'actuado' && tipo !== 'ignorado') {
+    throw new Error(`registrarFeedback: tipo inválido "${tipo}" (esperado actuado|ignorado)`);
+  }
+  const tele = leerTelemetriaPropose(baseDir);
+  const c = tele.categorias[categoria] || _catVacia();
+  c[tipo] += 1;
+  c.ultima_ts = hoyISO || new Date().toISOString();
+  _recomputarSilenciada(c);
+  tele.categorias[categoria] = c;
+  _persistir(baseDir, tele);
+  return tele;
+}
+
+/** Set de categorías silenciadas según la telemetría de propose. */
+function categoriasSilenciadasPropose(baseDir) {
+  const tele = leerTelemetriaPropose(baseDir);
+  if (briefing && briefing.categoriasSilenciadas) {
+    return briefing.categoriasSilenciadas(tele);
+  }
+  const set = new Set();
+  for (const [cat, c] of Object.entries(tele.categorias || {})) {
+    if (c && c.silenciada) set.add(cat);
+  }
+  return set;
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const MAX_DIFF_BUFFER = 32 * 1024 * 1024; // 32 MiB — tope de salida de git diff
+// Rango git válido: refs/SHAs y rangos `a..b` / `a...b`. Rechaza flags (`--output`,
+// `-G`) que git interpretaría aunque execFileSync evita el shell.
+const RE_RANGO_VALIDO = /^[A-Za-z0-9_./@~^-]+(\.\.\.?[A-Za-z0-9_./@~^-]+)?$/;
+
+function _gitDiff(rango) {
+  // execFileSync con array de args: no pasa por shell. Además se valida el rango
+  // y se usa el separador `--` para forzar que git lo trate como ref, no flag.
+  const r = rango || 'HEAD~1..HEAD';
+  if (!RE_RANGO_VALIDO.test(r)) return { paths: [], diff: '' };
+  try {
+    const paths = execFileSync('git', ['diff', '--name-only', r, '--'], { encoding: 'utf8' })
+      .split('\n').map((s) => s.trim()).filter(Boolean);
+    const diff = execFileSync('git', ['diff', r, '--'], { encoding: 'utf8', maxBuffer: MAX_DIFF_BUFFER });
+    return { paths, diff };
+  } catch (_) {
+    return { paths: [], diff: '' };
+  }
+}
+
+function main(argv) {
+  // Opt-out: SWL_PROPOSE=0 → silencio inmediato.
+  if (process.env.SWL_PROPOSE === '0') return 0;
+  const args = argv.slice(2);
+  let rango = 'HEAD~1..HEAD';
+  for (const a of args) {
+    if (a.startsWith('--rango=')) rango = a.slice('--rango='.length);
+  }
+  const baseDir = process.cwd();
+  const { paths, diff } = _gitDiff(rango);
+  const { señales } = evaluarSenales(paths, diff);
+  registrarPropose(baseDir, señales);
+  const anexo = formatearAnexo(señales, categoriasSilenciadasPropose(baseDir));
+  if (anexo) process.stdout.write(anexo + '\n');
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = {
+  detectarAuthPiiPagos,
+  detectarMigracionSchema,
+  evaluarSenales,
+  formatearAnexo,
+  leerTelemetriaPropose,
+  registrarPropose,
+  registrarFeedback,
+  categoriasSilenciadasPropose,
+};

package/hooks/session-briefing.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: session-briefing.js
+ * Tipo: SessionStart
+ *
+ * Briefing proactivo de inicio de sesión (Fase 12, ADR-0036). Al abrir sesión
+ * en un proyecto con `.planning/`, presenta un digest no solicitado de señales
+ * accionables que el usuario no sabía que tenía que preguntar: ADRs Propuestos
+ * con reevaluación vencida, deuda con trigger por fecha cumplido, nudges sin
+ * accionar, gates en calibración con ventana cumplida, y trabajo de retoma
+ * pendiente. Silencio total cuando no hay señales nuevas.
+ *
+ * Solo lecturas de filesystem ya computado: cero LLM, cero red, presupuesto
+ * <200ms (REQ-12-02). Las señales caras viven en `/swl:briefing`. SIEMPRE sale 0.
+ *
+ * Zero-deps. Opt-out: SWL_BRIEFING=0. Zero-config: sin `.planning/` → silencio.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Require con fallback dual: el instalador aplana `hooks/lib/X.js → <hooks>/X.js`
+// en el destino, pero en el repo madre vive en `lib/`. Cubre ambos layouts (D-17).
+function requireDual(nombre) {
+  try {
+    return require(`./lib/${nombre}`);
+  } catch (e1) {
+    if (e1 && e1.code !== 'MODULE_NOT_FOUND') throw e1;
+    return require(`./${nombre}`);
+  }
+}
+
+let briefing;
+let atomicWriteJSON;
+try {
+  briefing = requireDual('briefing');
+} catch (_) {
+  briefing = null;
+}
+try {
+  ({ atomicWriteJSON } = requireDual('atomic-write'));
+} catch (_) {
+  atomicWriteJSON = (p, obj) => fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+}
+
+let inputRaw = '';
+process.stdin.on('data', (c) => { inputRaw += c; });
+
+process.stdin.on('end', () => {
+  try {
+    if (process.env.SWL_BRIEFING === '0') return; // opt-out
+    if (!briefing) return;                          // lib ausente: degradar a silencio
+
+    const cwd = process.cwd();
+    if (!fs.existsSync(path.join(cwd, '.planning'))) return; // zero-config
+
+    const hoy = new Date();
+    const items = briefing.recolectarTodo(cwd, hoy);
+    const estadoPrevio = briefing.leerEstadoBriefing(cwd);
+    const dia = hoy.toISOString().slice(0, 10);
+
+    // Telemetría de aceptación (D-18, REQ-12-05): se actualiza SIEMPRE que el
+    // hook corre, comparando lo visto antes con lo presente ahora — independiente
+    // del dedupe de display. Alimenta a perfilador-usuario-swl para callar
+    // categorías que el usuario ignora consistentemente.
+    let silenciadas = new Set();
+    try {
+      const telePrev = briefing.leerTelemetria(cwd);
+      const teleNueva = briefing.actualizarTelemetria(telePrev, items, hoy.toISOString());
+      silenciadas = briefing.categoriasSilenciadas(teleNueva);
+      const dir = path.join(cwd, '.planning', 'user-profile');
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      atomicWriteJSON(path.join(dir, 'briefing-telemetria.json'), teleNueva);
+    } catch (_) { /* telemetría best-effort */ }
+
+    const digest = briefing.armarDigest(items, estadoPrevio, dia, {
+      categoriasSilenciadas: silenciadas,
+    });
+    if (!digest) return; // silencio total: sin señales nuevas
+
+    // Persistir el estado de dedupe (best-effort).
+    try {
+      const dir = path.join(cwd, '.planning', 'user-profile');
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      atomicWriteJSON(path.join(dir, 'briefing-estado.json'), digest.estado);
+    } catch (_) { /* persistir es best-effort; no romper el digest */ }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: digest.texto,
+      },
+    };
+    process.stdout.write(JSON.stringify(output));
+  } catch (_) { /* silencioso: el hook nunca bloquea la sesión */ }
+});