@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/lib/propose-step.js

@@ -1,358 +1,358 @@
-'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,
-  main,
-};
+'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,
+  main,
+};