@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/ciclo-autonomo/puente-degradacion.js

@@ -1,240 +1,240 @@
-'use strict';
-
-/**
- * puente-degradacion.js — Cierra el lazo entre APRENDIZAJES.md (memoria en
- * prosa) y los instintos derivados en `instintos/proyecto.yaml` (memoria
- * estructurada). Cuando `hooks/degradacion-instintos.js` marca una entrada
- * de APRENDIZAJES como `**[DEGRADADO: fecha]**` (tras 3 contradicciones,
- * ver `hooks/degradacion-instintos.js:216-222`), ese hecho nunca bajaba la
- * confidence del instinto YAML que se derivó de esa misma entrada — el
- * puente cierra ese lazo (Fase 21, ADR-0041/0042).
- *
- * `puentear(baseDir, {ahora})` es de solo lectura sobre APRENDIZAJES.md
- * (nunca lo escribe) y persiste sus cambios en `instintos/proyecto.yaml`
- * únicamente cuando hubo al menos un match (`bajados > 0`).
- *
- * ─────────────────────────────────────────────────────────────────────────
- * Criterio de matching (decisión de diseño deliberadamente conservadora):
- *
- *   "Mejor NO matchear que matchear mal" — un falso positivo degrada un
- *   instinto sano; un falso negativo simplemente pospone la degradación al
- *   próximo aprendizaje que sí matchee con más señal.
- *
- * 1. Candidatos: solo instintos con `source` que mencione "aprendizajes"
- *    (típicamente `source: "APRENDIZAJES.md"`) o con `seccion_origen` no
- *    vacío — es decir, instintos derivados de esa memoria, nunca instintos
- *    de otro origen (ej. instintos sembrados manualmente sin sección).
- * 2. Se extraen keywords normalizadas (minúsculas, sin acentos, ≥4 letras,
- *    sin stopwords) del título del aprendizaje degradado y, por el lado del
- *    instinto, de la unión de `pattern` + `description` + `seccion_origen`.
- * 3. Match = al menos `UMBRAL_MIN_COMPARTIDAS` (2) keywords compartidas Y
- *    al menos `UMBRAL_COBERTURA` (40%) de las keywords del aprendizaje
- *    cubiertas por el instinto. El umbral doble evita que una sola palabra
- *    genérica compartida ("orquestador" solo) dispare una degradación, y
- *    evita que un instinto con vocabulario enorme absorba matches por pura
- *    probabilidad (la cobertura se mide sobre el lado más corto: el título
- *    del aprendizaje, no el instinto).
- *
- * NUNCA usar similitud léxica difusa (Levenshtein, embeddings) — este es el
- * motor Nivel 0 (determinista, sin LLM, ADR-0042); la heurística de keywords
- * es intencionalmente simple y auditable.
- *
- * @module scripts/lib/ciclo-autonomo/puente-degradacion
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const { leerInstintos, escribirInstintos } = require('./yaml-instintos');
-const { shouldAutoDeprecate } = require('../scoring-instintos');
-
-// ─────────────────────────────────────────────────────────────────────────
-// Constantes del criterio de matching
-// ─────────────────────────────────────────────────────────────────────────
-
-const LONGITUD_MINIMA_KEYWORD = 4;
-const UMBRAL_MIN_COMPARTIDAS = 2;
-const UMBRAL_COBERTURA = 0.4;
-const UMBRAL_CONTRADICTIONS_DEGRADACION = 3;
-const RAZON_DEGRADACION = 'aprendizaje origen degradado en APRENDIZAJES.md';
-
-const REGEX_DEGRADADO = /^\*\*\[DEGRADADO:\s*([^\]]+)\]\*\*/;
-// Mismo patrón que hooks/degradacion-instintos.js:leerEntradas() usa para
-// extraer el título legible de la entrada a partir del encabezado `## `.
-const REGEX_ENCABEZADO = /^##\s+\[\d{4}-\d{2}-\d{2}\]\s+\w+[-\w]*\s+—\s+/;
-
-const STOPWORDS = new Set([
-  'para', 'con', 'que', 'los', 'las', 'del', 'una', 'uno', 'este', 'esta',
-  'estos', 'estas', 'como', 'desde', 'entre', 'sobre', 'cuando', 'donde',
-  'pero', 'sin', 'tras', 'hacia', 'segun', 'según', 'muy', 'mas', 'más',
-  'menos', 'todo', 'toda', 'todos', 'todas', 'cada', 'otro', 'otra',
-  'otros', 'otras', 'ser', 'esta', 'están', 'debe', 'deben', 'hay',
-]);
-
-// ─────────────────────────────────────────────────────────────────────────
-// Utilidades de keywords normalizadas
-// ─────────────────────────────────────────────────────────────────────────
-
-function normalizarPalabra(palabra) {
-  // NFD descompone "ó" en "o" + diacrítico combinante (rango Unicode U+0300-U+036F);
-  // quitarlo deja el equivalente ASCII sin acentos para comparar keywords.
-  return palabra.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
-}
-
-/** Extrae el set de keywords normalizadas (≥4 letras, sin stopwords) de un texto. */
-function extraerKeywords(texto) {
-  if (!texto) return new Set();
-  const palabras = String(texto)
-    .split(/[^A-Za-zÀ-ÿ0-9]+/)
-    .map(normalizarPalabra)
-    .filter((p) => p.length >= LONGITUD_MINIMA_KEYWORD && !STOPWORDS.has(p));
-  return new Set(palabras);
-}
-
-/**
- * Determina si dos sets de keywords "matchean" bajo el criterio conservador
- * documentado arriba: compartidas ≥ UMBRAL_MIN_COMPARTIDAS Y cobertura del
- * lado del aprendizaje ≥ UMBRAL_COBERTURA.
- */
-function esMatch(keywordsAprendizaje, keywordsInstinto) {
-  if (keywordsAprendizaje.size === 0 || keywordsInstinto.size === 0) return false;
-
-  let compartidas = 0;
-  keywordsAprendizaje.forEach((k) => {
-    if (keywordsInstinto.has(k)) compartidas += 1;
-  });
-
-  const cobertura = compartidas / keywordsAprendizaje.size;
-  return compartidas >= UMBRAL_MIN_COMPARTIDAS && cobertura >= UMBRAL_COBERTURA;
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Lectura (solo lectura) de APRENDIZAJES.md
-// ─────────────────────────────────────────────────────────────────────────
-
-/**
- * Lee `APRENDIZAJES.md` y devuelve las entradas marcadas `**[DEGRADADO: ...]**`
- * (formato exacto que escribe `hooks/degradacion-instintos.js:218`), con el
- * título de la entrada y sus keywords ya normalizadas. Nunca escribe el
- * archivo — es puramente de lectura.
- *
- * @param {string} rutaAprendizajes
- * @returns {Array<{titulo: string, fecha: string, keywords: Set<string>}>}
- */
-function leerAprendizajesDegradados(rutaAprendizajes) {
-  const contenido = fs.readFileSync(rutaAprendizajes, 'utf8');
-  const lineas = contenido.split(/\r\n|\n/);
-  const degradados = [];
-
-  for (let i = 0; i < lineas.length; i++) {
-    if (!lineas[i].startsWith('## ')) continue;
-
-    const titulo = lineas[i].replace(REGEX_ENCABEZADO, '').trim();
-
-    let fin = i + 1;
-    while (fin < lineas.length && !lineas[fin].startsWith('## ')) fin += 1;
-
-    let fechaDegradado = null;
-    for (let j = i + 1; j < fin; j++) {
-      const m = lineas[j].match(REGEX_DEGRADADO);
-      if (m) { fechaDegradado = m[1].trim(); break; }
-    }
-
-    if (fechaDegradado) {
-      degradados.push({ titulo, fecha: fechaDegradado, keywords: extraerKeywords(titulo) });
-    }
-  }
-
-  return degradados;
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Candidatos e instintos
-// ─────────────────────────────────────────────────────────────────────────
-
-/** Un instinto es candidato al puente si fue derivado de APRENDIZAJES.md. */
-function esCandidatoDerivado(instinto) {
-  const source = String(instinto.source || '').toLowerCase();
-  const tieneSeccionOrigen = typeof instinto.seccion_origen === 'string'
-    && instinto.seccion_origen.trim() !== '';
-  return source.includes('aprendizajes') || tieneSeccionOrigen;
-}
-
-function keywordsDeInstinto(instinto) {
-  const texto = [instinto.pattern, instinto.description, instinto.seccion_origen]
-    .filter((v) => typeof v === 'string')
-    .join(' ');
-  return extraerKeywords(texto);
-}
-
-function fechaLocal(ahora) {
-  const d = ahora instanceof Date ? ahora : (ahora ? new Date(ahora) : new Date());
-  return d.toLocaleDateString('sv');
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// API pública
-// ─────────────────────────────────────────────────────────────────────────
-
-/**
- * Baja la confidence (vía `contradictions`) de los instintos de
- * `instintos/proyecto.yaml` cuyo aprendizaje de origen fue marcado
- * `**[DEGRADADO]**` en `.planning/APRENDIZAJES.md`.
- *
- * Idempotente: un instinto ya marcado `degradado_por_puente: true` nunca
- * vuelve a incrementarse en corridas subsecuentes, sin importar cuántas
- * entradas degradadas nuevas matcheen con él.
- *
- * @param {string} baseDir - Raíz del proyecto (o sandbox de test).
- * @param {{ahora?: Date|string}} [opts]
- * @returns {{bajados: number}}
- */
-function puentear(baseDir, { ahora } = {}) {
-  const rutaAprendizajes = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
-  const rutaProyecto = path.join(baseDir, 'instintos', 'proyecto.yaml');
-
-  if (!fs.existsSync(rutaAprendizajes) || !fs.existsSync(rutaProyecto)) {
-    return { bajados: 0 };
-  }
-
-  const aprendizajesDegradados = leerAprendizajesDegradados(rutaAprendizajes);
-  if (aprendizajesDegradados.length === 0) return { bajados: 0 };
-
-  const datos = leerInstintos(rutaProyecto);
-  const hoy = fechaLocal(ahora);
-  let bajados = 0;
-
-  datos.instintos.forEach((instinto) => {
-    if (instinto.degradado_por_puente) return; // idempotencia: ya bajado antes
-    if (!esCandidatoDerivado(instinto)) return;
-
-    const keywordsInstinto = keywordsDeInstinto(instinto);
-    if (keywordsInstinto.size === 0) return;
-
-    const hayMatch = aprendizajesDegradados.some(
-      (aprendizaje) => esMatch(aprendizaje.keywords, keywordsInstinto)
-    );
-    if (!hayMatch) return;
-
-    instinto.contradictions = (instinto.contradictions || 0) + 1;
-    instinto.degradado_por_puente = true;
-    instinto.origen = 'ciclo-autonomo';
-    instinto.last_validated_at = hoy;
-
-    if (instinto.contradictions >= UMBRAL_CONTRADICTIONS_DEGRADACION || shouldAutoDeprecate(instinto)) {
-      instinto.status = 'degraded';
-      instinto.deprecation_reason = RAZON_DEGRADACION;
-    }
-
-    bajados += 1;
-  });
-
-  if (bajados === 0) return { bajados: 0 };
-
-  escribirInstintos(rutaProyecto, datos);
-  return { bajados };
-}
-
-module.exports = {
-  puentear,
-};
+'use strict';
+
+/**
+ * puente-degradacion.js — Cierra el lazo entre APRENDIZAJES.md (memoria en
+ * prosa) y los instintos derivados en `instintos/proyecto.yaml` (memoria
+ * estructurada). Cuando `hooks/degradacion-instintos.js` marca una entrada
+ * de APRENDIZAJES como `**[DEGRADADO: fecha]**` (tras 3 contradicciones,
+ * ver `hooks/degradacion-instintos.js:216-222`), ese hecho nunca bajaba la
+ * confidence del instinto YAML que se derivó de esa misma entrada — el
+ * puente cierra ese lazo (Fase 21, ADR-0041/0042).
+ *
+ * `puentear(baseDir, {ahora})` es de solo lectura sobre APRENDIZAJES.md
+ * (nunca lo escribe) y persiste sus cambios en `instintos/proyecto.yaml`
+ * únicamente cuando hubo al menos un match (`bajados > 0`).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * Criterio de matching (decisión de diseño deliberadamente conservadora):
+ *
+ *   "Mejor NO matchear que matchear mal" — un falso positivo degrada un
+ *   instinto sano; un falso negativo simplemente pospone la degradación al
+ *   próximo aprendizaje que sí matchee con más señal.
+ *
+ * 1. Candidatos: solo instintos con `source` que mencione "aprendizajes"
+ *    (típicamente `source: "APRENDIZAJES.md"`) o con `seccion_origen` no
+ *    vacío — es decir, instintos derivados de esa memoria, nunca instintos
+ *    de otro origen (ej. instintos sembrados manualmente sin sección).
+ * 2. Se extraen keywords normalizadas (minúsculas, sin acentos, ≥4 letras,
+ *    sin stopwords) del título del aprendizaje degradado y, por el lado del
+ *    instinto, de la unión de `pattern` + `description` + `seccion_origen`.
+ * 3. Match = al menos `UMBRAL_MIN_COMPARTIDAS` (2) keywords compartidas Y
+ *    al menos `UMBRAL_COBERTURA` (40%) de las keywords del aprendizaje
+ *    cubiertas por el instinto. El umbral doble evita que una sola palabra
+ *    genérica compartida ("orquestador" solo) dispare una degradación, y
+ *    evita que un instinto con vocabulario enorme absorba matches por pura
+ *    probabilidad (la cobertura se mide sobre el lado más corto: el título
+ *    del aprendizaje, no el instinto).
+ *
+ * NUNCA usar similitud léxica difusa (Levenshtein, embeddings) — este es el
+ * motor Nivel 0 (determinista, sin LLM, ADR-0042); la heurística de keywords
+ * es intencionalmente simple y auditable.
+ *
+ * @module scripts/lib/ciclo-autonomo/puente-degradacion
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { leerInstintos, escribirInstintos } = require('./yaml-instintos');
+const { shouldAutoDeprecate } = require('../scoring-instintos');
+
+// ─────────────────────────────────────────────────────────────────────────
+// Constantes del criterio de matching
+// ─────────────────────────────────────────────────────────────────────────
+
+const LONGITUD_MINIMA_KEYWORD = 4;
+const UMBRAL_MIN_COMPARTIDAS = 2;
+const UMBRAL_COBERTURA = 0.4;
+const UMBRAL_CONTRADICTIONS_DEGRADACION = 3;
+const RAZON_DEGRADACION = 'aprendizaje origen degradado en APRENDIZAJES.md';
+
+const REGEX_DEGRADADO = /^\*\*\[DEGRADADO:\s*([^\]]+)\]\*\*/;
+// Mismo patrón que hooks/degradacion-instintos.js:leerEntradas() usa para
+// extraer el título legible de la entrada a partir del encabezado `## `.
+const REGEX_ENCABEZADO = /^##\s+\[\d{4}-\d{2}-\d{2}\]\s+\w+[-\w]*\s+—\s+/;
+
+const STOPWORDS = new Set([
+  'para', 'con', 'que', 'los', 'las', 'del', 'una', 'uno', 'este', 'esta',
+  'estos', 'estas', 'como', 'desde', 'entre', 'sobre', 'cuando', 'donde',
+  'pero', 'sin', 'tras', 'hacia', 'segun', 'según', 'muy', 'mas', 'más',
+  'menos', 'todo', 'toda', 'todos', 'todas', 'cada', 'otro', 'otra',
+  'otros', 'otras', 'ser', 'esta', 'están', 'debe', 'deben', 'hay',
+]);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Utilidades de keywords normalizadas
+// ─────────────────────────────────────────────────────────────────────────
+
+function normalizarPalabra(palabra) {
+  // NFD descompone "ó" en "o" + diacrítico combinante (rango Unicode U+0300-U+036F);
+  // quitarlo deja el equivalente ASCII sin acentos para comparar keywords.
+  return palabra.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+}
+
+/** Extrae el set de keywords normalizadas (≥4 letras, sin stopwords) de un texto. */
+function extraerKeywords(texto) {
+  if (!texto) return new Set();
+  const palabras = String(texto)
+    .split(/[^A-Za-zÀ-ÿ0-9]+/)
+    .map(normalizarPalabra)
+    .filter((p) => p.length >= LONGITUD_MINIMA_KEYWORD && !STOPWORDS.has(p));
+  return new Set(palabras);
+}
+
+/**
+ * Determina si dos sets de keywords "matchean" bajo el criterio conservador
+ * documentado arriba: compartidas ≥ UMBRAL_MIN_COMPARTIDAS Y cobertura del
+ * lado del aprendizaje ≥ UMBRAL_COBERTURA.
+ */
+function esMatch(keywordsAprendizaje, keywordsInstinto) {
+  if (keywordsAprendizaje.size === 0 || keywordsInstinto.size === 0) return false;
+
+  let compartidas = 0;
+  keywordsAprendizaje.forEach((k) => {
+    if (keywordsInstinto.has(k)) compartidas += 1;
+  });
+
+  const cobertura = compartidas / keywordsAprendizaje.size;
+  return compartidas >= UMBRAL_MIN_COMPARTIDAS && cobertura >= UMBRAL_COBERTURA;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Lectura (solo lectura) de APRENDIZAJES.md
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Lee `APRENDIZAJES.md` y devuelve las entradas marcadas `**[DEGRADADO: ...]**`
+ * (formato exacto que escribe `hooks/degradacion-instintos.js:218`), con el
+ * título de la entrada y sus keywords ya normalizadas. Nunca escribe el
+ * archivo — es puramente de lectura.
+ *
+ * @param {string} rutaAprendizajes
+ * @returns {Array<{titulo: string, fecha: string, keywords: Set<string>}>}
+ */
+function leerAprendizajesDegradados(rutaAprendizajes) {
+  const contenido = fs.readFileSync(rutaAprendizajes, 'utf8');
+  const lineas = contenido.split(/\r\n|\n/);
+  const degradados = [];
+
+  for (let i = 0; i < lineas.length; i++) {
+    if (!lineas[i].startsWith('## ')) continue;
+
+    const titulo = lineas[i].replace(REGEX_ENCABEZADO, '').trim();
+
+    let fin = i + 1;
+    while (fin < lineas.length && !lineas[fin].startsWith('## ')) fin += 1;
+
+    let fechaDegradado = null;
+    for (let j = i + 1; j < fin; j++) {
+      const m = lineas[j].match(REGEX_DEGRADADO);
+      if (m) { fechaDegradado = m[1].trim(); break; }
+    }
+
+    if (fechaDegradado) {
+      degradados.push({ titulo, fecha: fechaDegradado, keywords: extraerKeywords(titulo) });
+    }
+  }
+
+  return degradados;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Candidatos e instintos
+// ─────────────────────────────────────────────────────────────────────────
+
+/** Un instinto es candidato al puente si fue derivado de APRENDIZAJES.md. */
+function esCandidatoDerivado(instinto) {
+  const source = String(instinto.source || '').toLowerCase();
+  const tieneSeccionOrigen = typeof instinto.seccion_origen === 'string'
+    && instinto.seccion_origen.trim() !== '';
+  return source.includes('aprendizajes') || tieneSeccionOrigen;
+}
+
+function keywordsDeInstinto(instinto) {
+  const texto = [instinto.pattern, instinto.description, instinto.seccion_origen]
+    .filter((v) => typeof v === 'string')
+    .join(' ');
+  return extraerKeywords(texto);
+}
+
+function fechaLocal(ahora) {
+  const d = ahora instanceof Date ? ahora : (ahora ? new Date(ahora) : new Date());
+  return d.toLocaleDateString('sv');
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// API pública
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Baja la confidence (vía `contradictions`) de los instintos de
+ * `instintos/proyecto.yaml` cuyo aprendizaje de origen fue marcado
+ * `**[DEGRADADO]**` en `.planning/APRENDIZAJES.md`.
+ *
+ * Idempotente: un instinto ya marcado `degradado_por_puente: true` nunca
+ * vuelve a incrementarse en corridas subsecuentes, sin importar cuántas
+ * entradas degradadas nuevas matcheen con él.
+ *
+ * @param {string} baseDir - Raíz del proyecto (o sandbox de test).
+ * @param {{ahora?: Date|string}} [opts]
+ * @returns {{bajados: number}}
+ */
+function puentear(baseDir, { ahora } = {}) {
+  const rutaAprendizajes = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
+  const rutaProyecto = path.join(baseDir, 'instintos', 'proyecto.yaml');
+
+  if (!fs.existsSync(rutaAprendizajes) || !fs.existsSync(rutaProyecto)) {
+    return { bajados: 0 };
+  }
+
+  const aprendizajesDegradados = leerAprendizajesDegradados(rutaAprendizajes);
+  if (aprendizajesDegradados.length === 0) return { bajados: 0 };
+
+  const datos = leerInstintos(rutaProyecto);
+  const hoy = fechaLocal(ahora);
+  let bajados = 0;
+
+  datos.instintos.forEach((instinto) => {
+    if (instinto.degradado_por_puente) return; // idempotencia: ya bajado antes
+    if (!esCandidatoDerivado(instinto)) return;
+
+    const keywordsInstinto = keywordsDeInstinto(instinto);
+    if (keywordsInstinto.size === 0) return;
+
+    const hayMatch = aprendizajesDegradados.some(
+      (aprendizaje) => esMatch(aprendizaje.keywords, keywordsInstinto)
+    );
+    if (!hayMatch) return;
+
+    instinto.contradictions = (instinto.contradictions || 0) + 1;
+    instinto.degradado_por_puente = true;
+    instinto.origen = 'ciclo-autonomo';
+    instinto.last_validated_at = hoy;
+
+    if (instinto.contradictions >= UMBRAL_CONTRADICTIONS_DEGRADACION || shouldAutoDeprecate(instinto)) {
+      instinto.status = 'degraded';
+      instinto.deprecation_reason = RAZON_DEGRADACION;
+    }
+
+    bajados += 1;
+  });
+
+  if (bajados === 0) return { bajados: 0 };
+
+  escribirInstintos(rutaProyecto, datos);
+  return { bajados };
+}
+
+module.exports = {
+  puentear,
+};