@saulwade/swl-ses 2.0.0 → 2.2.0

package/hooks/lib/briefing.js

@@ -0,0 +1,474 @@
+'use strict';
+
+/**
+ * briefing.js — Recolectores de señales para el briefing proactivo de sesión.
+ *
+ * Fase 12 (ADR-0036). Cada recolector es una función PURA que recibe `baseDir`
+ * (raíz del proyecto destino) y `hoy` (Date inyectable para testabilidad) y
+ * devuelve un array de ítems `{ categoria, titulo, accion, hash }`:
+ *   - categoria: clave estable de la señal (para telemetría y dedupe por grupo).
+ *   - titulo:    texto corto de qué pasa.
+ *   - accion:    comando ejecutable concreto (REQ-12-03: nunca consejo vago).
+ *   - hash:      sha1 corto de categoria+titulo, para dedupe entre digests (D-18).
+ *
+ * Solo lecturas de filesystem ya computado: cero LLM, cero red, presupuesto
+ * <200ms (REQ-12-02). Las señales caras (CVEs, cobertura, hubs del grafo) viven
+ * en el comando `/swl:briefing`, no aquí (D-12).
+ *
+ * Zero-deps. El hook session-briefing.js consume esta lib con require de
+ * fallback dual (repo madre `./lib/briefing` vs destino aplanado `./briefing`).
+ *
+ * @module hooks/lib/briefing
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Métricas DORA (Fase 15, ADR-0039): require tolerante. En modo de instalación
+// `flat` el require cross-dir hooks/lib → scripts/lib no resuelve y el recolector
+// degrada a silencio; en modo `copy` (default) resuelve y el aviso proactivo
+// funciona. El recolector usa SOLO git (rápido); NUNCA invoca gh.
+let detectarDegradacionEntrega = null;
+try {
+  ({ detectarDegradacionEntrega } = require('../../scripts/lib/git-metricas'));
+} catch {
+  try {
+    ({ detectarDegradacionEntrega } = require('./git-metricas'));
+  } catch {
+    detectarDegradacionEntrega = null;
+  }
+}
+
+const VENTANA_CALIBRACION_MS = 14 * 24 * 3600 * 1000; // 14 días (ADR-0034/0035)
+
+// Gates en calibración → kind de su nudge (conocimiento de dominio, Fase 10).
+const GATES_CALIBRABLES = {
+  'spec-gate.js': 'spec-gate',
+  'tdd-gate.js': 'tdd-red-evidence',
+};
+
+// ─── utilidades ──────────────────────────────────────────────────────────────
+
+function leerTexto(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function hashItem(categoria, titulo) {
+  return crypto.createHash('sha1').update(`${categoria}\u0000${titulo}`).digest('hex').slice(0, 10);
+}
+
+function item(categoria, titulo, accion) {
+  return { categoria, titulo, accion, hash: hashItem(categoria, titulo) };
+}
+
+/** Primera fecha ISO `YYYY-MM-DD` de un texto, como Date (UTC) o null. */
+function primeraFechaISO(texto) {
+  const m = (texto || '').match(/(\d{4})-(\d{2})-(\d{2})/);
+  if (!m) return null;
+  const d = new Date(`${m[1]}-${m[2]}-${m[3]}T00:00:00Z`);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** Lee `.planning/evolution/nudges.jsonl` como array de objetos (tolera líneas corruptas). */
+function leerNudges(baseDir) {
+  const txt = leerTexto(path.join(baseDir, '.planning', 'evolution', 'nudges.jsonl'));
+  if (!txt) return [];
+  const out = [];
+  for (const linea of txt.split('\n')) {
+    const t = linea.trim();
+    if (!t) continue;
+    try {
+      out.push(JSON.parse(t));
+    } catch {
+      /* línea corrupta: ignorar */
+    }
+  }
+  return out;
+}
+
+// ─── recolectores ──────────────────────────────────────────────────────────
+
+/**
+ * ADRs en estado Propuesto cuya fecha de reevaluación ya pasó.
+ * Fuente: `.planning/adrs/README.md` (tabla `| # | Título | Estado | Fecha | Reevaluar |`).
+ */
+function adrsVencidos(baseDir, hoy = new Date()) {
+  const txt = leerTexto(path.join(baseDir, '.planning', 'adrs', 'README.md'));
+  if (!txt) return [];
+  const out = [];
+  for (const linea of txt.split('\n')) {
+    if (!linea.includes('|')) continue;
+    const celdas = linea.split('|').map((c) => c.trim());
+    // celdas: ['', '#', 'Título', 'Estado', 'Fecha', 'Reevaluar', '']
+    if (celdas.length < 6) continue;
+    const num = celdas[1];
+    const titulo = celdas[2];
+    const estado = celdas[3];
+    const reevaluar = celdas[5];
+    if (!/^\d{3,4}$/.test(num)) continue; // fila de datos (no encabezado/separador)
+    if (!/Propuesto/i.test(estado)) continue;
+    const fecha = primeraFechaISO(reevaluar);
+    if (!fecha || fecha.getTime() > hoy.getTime()) continue;
+    out.push(
+      item(
+        'adr-vencido',
+        `ADR-${num} Propuesto con reevaluación vencida (${reevaluar.replace(/\*/g, '')})`,
+        `Revisar .planning/adrs/${num}-*.md y resolver (aceptar / descartar / extender)`
+      )
+    );
+  }
+  return out;
+}
+
+/**
+ * Deuda técnica Abierta cuyo trigger verificable contiene una fecha ISO ya pasada.
+ * Solo fechas (D-16): los triggers en prosa libre quedan para `/swl:briefing`.
+ * Fuente: `.planning/DEUDA-TECNICA.md` (entradas `## DT-X —`, `**Estado**: Abierta`).
+ */
+function deudaTriggerCumplido(baseDir, hoy = new Date()) {
+  const txt = leerTexto(path.join(baseDir, '.planning', 'DEUDA-TECNICA.md'));
+  if (!txt) return [];
+  const out = [];
+  // Partir por encabezados `## DT-...` / `## DA-...` / `## OP-...`
+  const bloques = txt.split(/\n(?=## (?:DT|DA|OP)-)/);
+  for (const bloque of bloques) {
+    const cab = bloque.match(/^##\s+((?:DT|DA|OP)-[A-Z0-9-]+)\s*(?:—\s*(.*))?/m);
+    if (!cab) continue;
+    const id = cab[1];
+    if (!/\*\*Estado\*\*\s*:\s*Abierta/i.test(bloque)) continue;
+    // Buscar fecha ISO en la sección de trigger (o en todo el bloque como fallback)
+    const triggerSec = bloque.split(/###\s*Trigger/i)[1] || bloque;
+    const fecha = primeraFechaISO(triggerSec);
+    if (!fecha || fecha.getTime() > hoy.getTime()) continue;
+    out.push(
+      item(
+        'deuda-trigger',
+        `${id}: trigger con fecha cumplida (${fecha.toISOString().slice(0, 10)})`,
+        `Revisar .planning/DEUDA-TECNICA.md § ${id} y cerrar o re-planear`
+      )
+    );
+  }
+  return out;
+}
+
+/**
+ * Nudges sin accionar acumulados (formato nudge-tracker: { kind, accionado }).
+ * Las líneas legacy sin `kind` se ignoran.
+ */
+function nudgesPendientes(baseDir /*, hoy */) {
+  const nudges = leerNudges(baseDir).filter((n) => n && n.kind && n.accionado === false);
+  if (nudges.length === 0) return [];
+  const porKind = {};
+  for (const n of nudges) porKind[n.kind] = (porKind[n.kind] || 0) + 1;
+  const detalle = Object.entries(porKind)
+    .map(([k, c]) => `${k}×${c}`)
+    .join(', ');
+  return [
+    item(
+      'nudges-pendientes',
+      `${nudges.length} nudge(s) sin accionar (${detalle})`,
+      'Ejecutar /swl:evolucion-estado para revisarlos y accionar'
+    ),
+  ];
+}
+
+/**
+ * Gates en calibración (warn-only) cuya ventana de ~14 días ya se cumplió:
+ * blocking:false en hooks-config Y el nudge más antiguo de su kind ≥14 días.
+ * Señal de que toca decidir la promoción a blocking (ADR-0034/0035).
+ */
+function gatesEnCalibracion(baseDir, hoy = new Date(), opts = {}) {
+  const hooksConfigPath =
+    opts.hooksConfigPath || path.join(baseDir, 'manifiestos', 'hooks-config.json');
+  const txt = leerTexto(hooksConfigPath);
+  if (!txt) return [];
+  let config;
+  try {
+    config = JSON.parse(txt);
+  } catch {
+    return [];
+  }
+  const hooks = (config && config.hooks) || {};
+  const nudges = leerNudges(baseDir).filter((n) => n && n.kind && n.ts);
+  const out = [];
+  for (const [archivo, kind] of Object.entries(GATES_CALIBRABLES)) {
+    const entry = hooks[archivo];
+    if (!entry || entry.blocking !== false) continue; // ya promovido o ausente
+    const delKind = nudges
+      .map((n) => (n.kind === kind ? Date.parse(n.ts) : NaN))
+      .filter((t) => Number.isFinite(t));
+    if (delKind.length === 0) continue; // sin evidencia todavía
+    const masAntiguo = Math.min(...delKind);
+    if (hoy.getTime() - masAntiguo < VENTANA_CALIBRACION_MS) continue; // ventana no cumplida
+    out.push(
+      item(
+        'gate-calibracion',
+        `Gate ${archivo} en calibración con ventana cumplida (${delKind.length} nudge[s] kind:${kind})`,
+        `Revisar promoción a blocking (ADR-0034/0035) y flip en manifiestos/hooks-config.json`
+      )
+    );
+  }
+  return out;
+}
+
+/**
+ * Trabajo pendiente de retoma: existe `.planning/continue-here.md`.
+ */
+function continuePendiente(baseDir /*, hoy */) {
+  const p = path.join(baseDir, '.planning', 'continue-here.md');
+  const txt = leerTexto(p);
+  if (txt === null) return [];
+  const m = txt.match(/\*\*Checkpoint creado\*\*\s*:\s*(.+)/);
+  const cuando = m ? m[1].trim() : 'desconocido';
+  return [
+    item(
+      'continue-here',
+      `Checkpoint de retoma pendiente (${cuando})`,
+      'Leer .planning/continue-here.md y .planning/ESTADO.md para retomar'
+    ),
+  ];
+}
+
+/**
+ * Recolector DORA (Fase 15, REQ-15-07): avisa SOLO cuando la velocidad de entrega
+ * se degrada (deploy freq cae >50% o lead time mediano sube >50% vs la ventana
+ * previa). Git-only y rápido — NUNCA invoca `gh` (la latencia de gh queda para el
+ * subcomando bajo demanda). Opt-out: `SWL_DORA=0`. Silencio si la entrega es
+ * estable, si no hay repo git, o si la lib no resuelve (modo `flat`).
+ */
+function doraDegradado(baseDir, hoy = new Date()) {
+  if (process.env.SWL_DORA === '0') return [];
+  if (typeof detectarDegradacionEntrega !== 'function') return [];
+  let r;
+  try {
+    r = detectarDegradacionEntrega(baseDir, { hoy });
+  } catch {
+    return [];
+  }
+  if (!r || !r.disponible || !r.degradado) return [];
+  return [
+    item(
+      'dora-degradado',
+      `Velocidad de entrega degradada: ${r.motivo}`,
+      'Revisar con /swl:status dora'
+    ),
+  ];
+}
+
+/** Orden de prioridad de categorías para el digest (mayor primero). */
+const PRIORIDAD = [
+  'continue-here',
+  'gate-calibracion',
+  'deuda-trigger',
+  'dora-degradado',
+  'adr-vencido',
+  'nudges-pendientes',
+];
+
+/** Ejecuta todos los recolectores y devuelve el array plano de ítems. */
+function recolectarTodo(baseDir, hoy = new Date(), opts = {}) {
+  return [
+    ...continuePendiente(baseDir, hoy),
+    ...gatesEnCalibracion(baseDir, hoy, opts),
+    ...deudaTriggerCumplido(baseDir, hoy),
+    ...doraDegradado(baseDir, hoy),
+    ...adrsVencidos(baseDir, hoy),
+    ...nudgesPendientes(baseDir, hoy),
+  ];
+}
+
+const TOPE_DIGEST = 5; // D-13: máximo de ítems por digest
+
+/** Índice de prioridad de una categoría (menor = mayor prioridad). */
+function indicePrioridad(categoria) {
+  const i = PRIORIDAD.indexOf(categoria);
+  return i === -1 ? PRIORIDAD.length : i;
+}
+
+/**
+ * Arma el digest del briefing aplicando dedupe diario (D-15), tope de 5 con
+ * overflow (D-13), y sugerencia de `/swl:briefing` solo con volumen (D-14).
+ *
+ * @param {Array} items        ítems recolectados (recolectarTodo)
+ * @param {object} estadoPrevio { hashesPrevios: string[], dia: 'YYYY-MM-DD' }
+ * @param {string} dia          día actual 'YYYY-MM-DD' (inyectable)
+ * @returns {{ texto: string, estado: object, mostrados: string[] } | null}
+ *          null = silencio total (sin señales nuevas).
+ */
+function armarDigest(items, estadoPrevio = {}, dia, opts = {}) {
+  const hoyStr = dia || new Date().toISOString().slice(0, 10);
+  const mismoDia = estadoPrevio && estadoPrevio.dia === hoyStr;
+  const yaMostrados = mismoDia && Array.isArray(estadoPrevio.hashesPrevios)
+    ? new Set(estadoPrevio.hashesPrevios)
+    : new Set();
+
+  // Dedupe: en el mismo día, omitir ítems ya mostrados. Día nuevo → set vacío.
+  const frescos = (items || []).filter((it) => it && !yaMostrados.has(it.hash));
+  if (frescos.length === 0) return null; // silencio total (REQ-12-01)
+
+  // Categorías silenciadas (telemetría D-18): sus ítems no entran al top 5,
+  // van al final (overflow) para no copar el digest con señales que el usuario ignora.
+  const silenciadas = opts.categoriasSilenciadas instanceof Set ? opts.categoriasSilenciadas : new Set();
+
+  // Orden: prioridad de categoría, pero las silenciadas siempre al final.
+  frescos.sort((a, b) => {
+    const sa = silenciadas.has(a.categoria) ? 1 : 0;
+    const sb = silenciadas.has(b.categoria) ? 1 : 0;
+    if (sa !== sb) return sa - sb;
+    return indicePrioridad(a.categoria) - indicePrioridad(b.categoria);
+  });
+
+  const visibles = frescos.slice(0, TOPE_DIGEST);
+  const overflow = frescos.length - visibles.length;
+
+  const lineas = ['Briefing de sesión — señales pendientes:'];
+  for (const it of visibles) {
+    lineas.push(`— [${it.categoria}] ${it.titulo} → ${it.accion}`);
+  }
+  // Sugerencia de /swl:briefing SOLO con overflow (D-14).
+  if (overflow > 0) {
+    lineas.push(`+${overflow} señales más → ejecuta /swl:briefing para el análisis completo`);
+  }
+
+  // Estado nuevo: acumula los hashes mostrados HOY (frescos completos, no solo visibles —
+  // los de overflow también se consideran "vistos" para no re-listarlos mañana mismo).
+  const hashesMostrados = mismoDia
+    ? [...yaMostrados, ...frescos.map((it) => it.hash)]
+    : frescos.map((it) => it.hash);
+
+  return {
+    texto: lineas.join('\n'),
+    estado: { dia: hoyStr, hashesPrevios: [...new Set(hashesMostrados)] },
+    mostrados: visibles.map((it) => it.hash),
+  };
+}
+
+/** Lee el estado de dedupe persistido en `.planning/user-profile/briefing-estado.json`. */
+function leerEstadoBriefing(baseDir) {
+  const txt = leerTexto(path.join(baseDir, '.planning', 'user-profile', 'briefing-estado.json'));
+  if (!txt) return { dia: null, hashesPrevios: [] };
+  try {
+    const o = JSON.parse(txt);
+    return { dia: o.dia || null, hashesPrevios: Array.isArray(o.hashesPrevios) ? o.hashesPrevios : [] };
+  } catch {
+    return { dia: null, hashesPrevios: [] };
+  }
+}
+
+// ─── telemetría de aceptación (D-18, REQ-12-05) ──────────────────────────────
+
+const UMBRAL_IGNORADO = 3; // apariciones sin resolver para contar "ignorado"
+const RATIO_SILENCIO = 0.8; // ignorado/mostrado para silenciar la categoría
+const MIN_MUESTRAS_SILENCIO = 5; // mínimo de mostrados antes de silenciar
+
+function catVacia() {
+  return { mostrado: 0, actuado: 0, ignorado: 0, silenciada: false, ultima_ts: null };
+}
+
+/**
+ * Actualiza la telemetría de aceptación comparando lo visto antes con lo que
+ * sigue presente ahora (D-18: detección por resolución de señal, zero-LLM):
+ *   - señal que desaparece de los ítems actuales → "actuado" en su categoría.
+ *   - señal nueva → "mostrado" y entra a `vistos`.
+ *   - señal que persiste ≥UMBRAL_IGNORADO corridas → "ignorado" (una sola vez).
+ *   - categoría con ignorado/mostrado ≥RATIO_SILENCIO y ≥MIN_MUESTRAS → silenciada.
+ *
+ * @param {object} prev          { vistos:{hash:{categoria,veces,contadoIgnorado?}}, categorias:{} }
+ * @param {Array}  itemsActuales  ítems recolectados ahora
+ * @param {string} hoyISO         timestamp ISO de esta corrida
+ * @returns {object} telemetría nueva (consumible por perfilador-usuario-swl)
+ */
+function actualizarTelemetria(prev, itemsActuales, hoyISO) {
+  const vistos = { ...(prev && prev.vistos) };
+  const categorias = {};
+  for (const [k, v] of Object.entries((prev && prev.categorias) || {})) {
+    categorias[k] = { ...catVacia(), ...v };
+  }
+  const ensure = (cat) => {
+    if (!categorias[cat]) categorias[cat] = catVacia();
+    return categorias[cat];
+  };
+
+  const hashesActuales = new Set((itemsActuales || []).map((it) => it.hash));
+
+  // 1. Resueltos: lo que estaba visto y ya no aparece → actuado.
+  for (const [hash, info] of Object.entries(vistos)) {
+    if (!hashesActuales.has(hash)) {
+      ensure(info.categoria).actuado += 1;
+      ensure(info.categoria).ultima_ts = hoyISO;
+      delete vistos[hash];
+    }
+  }
+
+  // 2. Presentes ahora: nuevos (mostrado++) o persistentes (veces++ → ignorado).
+  for (const it of itemsActuales || []) {
+    const c = ensure(it.categoria);
+    c.ultima_ts = hoyISO;
+    if (!vistos[it.hash]) {
+      vistos[it.hash] = { categoria: it.categoria, veces: 1, contadoIgnorado: false };
+      c.mostrado += 1;
+    } else {
+      vistos[it.hash].veces += 1;
+      if (vistos[it.hash].veces >= UMBRAL_IGNORADO && !vistos[it.hash].contadoIgnorado) {
+        c.ignorado += 1;
+        vistos[it.hash].contadoIgnorado = true;
+      }
+    }
+  }
+
+  // 3. Silenciar categorías con ratio de ignorado alto.
+  for (const c of Object.values(categorias)) {
+    c.silenciada =
+      c.mostrado >= MIN_MUESTRAS_SILENCIO && c.ignorado / c.mostrado >= RATIO_SILENCIO;
+  }
+
+  return { vistos, categorias };
+}
+
+/** Lee la telemetría persistida en `.planning/user-profile/briefing-telemetria.json`. */
+function leerTelemetria(baseDir) {
+  const txt = leerTexto(path.join(baseDir, '.planning', 'user-profile', 'briefing-telemetria.json'));
+  if (!txt) return { vistos: {}, categorias: {} };
+  try {
+    const o = JSON.parse(txt);
+    return { vistos: o.vistos || {}, categorias: o.categorias || {} };
+  } catch {
+    return { vistos: {}, categorias: {} };
+  }
+}
+
+/** Conjunto de categorías actualmente silenciadas (para que armarDigest las degrade). */
+function categoriasSilenciadas(telemetria) {
+  const set = new Set();
+  for (const [cat, v] of Object.entries((telemetria && telemetria.categorias) || {})) {
+    if (v && v.silenciada) set.add(cat);
+  }
+  return set;
+}
+
+module.exports = {
+  adrsVencidos,
+  deudaTriggerCumplido,
+  nudgesPendientes,
+  gatesEnCalibracion,
+  continuePendiente,
+  doraDegradado,
+  recolectarTodo,
+  armarDigest,
+  leerEstadoBriefing,
+  actualizarTelemetria,
+  leerTelemetria,
+  categoriasSilenciadas,
+  PRIORIDAD,
+  TOPE_DIGEST,
+  VENTANA_CALIBRACION_MS,
+  UMBRAL_IGNORADO,
+  RATIO_SILENCIO,
+  MIN_MUESTRAS_SILENCIO,
+  _hashItem: hashItem,
+};