@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/ciclo-autonomo/writer-instintos.js

@@ -1,190 +1,190 @@
-'use strict';
-
-/**
- * writer-instintos.js — Aplica el scoring de `scoring-instintos.js` sobre
- * `instintos/proyecto.yaml` y persiste las transiciones de maduración
- * (Fase 21, T-04, REQ-21-01). Compone las funciones puras del scoring (que
- * NUNCA persisten) con el round-trip de `yaml-instintos.js` (T-03).
- *
- * Decisión de mapeo de campo (ver CLAUDE.md / 21-PLAN.md "Inteligencia del
- * codebase"): el YAML real usa `last_validated` (no `last_validated_at`).
- * `scoring-instintos.getValidatedDate()` YA contempla ese nombre como
- * fallback (`instinto.last_validated_at || instinto.last_validated || ...`),
- * así que no se requiere ningún mapeo al leer — los instintos se pasan tal
- * cual a `recomputeStatus`. Al refrescar la fecha de validación tras una
- * transición de estado, este writer escribe `last_validated` (el campo real
- * del schema), nunca `last_validated_at` (que es un campo interno del
- * scoring usado solo por `applyFeedback`, ajeno al schema persistido aquí).
- *
- * Orden de cómputo por instinto (necesario para idempotencia, ver tests):
- *   1. Recompute con el instinto ORIGINAL → decide si hay transición de
- *      estado (b/c/d) usando el effective_confidence previo al refresh.
- *   2. Si hubo transición, se refresca `last_validated` a `ahora`.
- *   3. Recompute FINAL sobre el instinto ya transicionado (con la fecha de
- *      validación definitiva) → ese valor es el que se persiste como
- *      `effective_confidence`/`maturity`. Sin este segundo paso, una
- *      segunda corrida con el mismo `ahora` recalcularía un decay distinto
- *      (0 días desde el refresh) y rompería la idempotencia.
- *
- * Zero-deps, CommonJS.
- *
- * @module scripts/lib/ciclo-autonomo/writer-instintos
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const {
-  recomputeStatus,
-  shouldAutoDeprecate,
-  ESTABLISHED_THRESHOLD,
-} = require('../scoring-instintos');
-const { leerInstintos, escribirInstintos } = require('./yaml-instintos');
-
-/** Ruta relativa del YAML de instintos de proyecto dentro del baseDir. */
-const RUTA_RELATIVA = path.join('instintos', 'proyecto.yaml');
-
-// Mismo valor numérico que ESTABLISHED_THRESHOLD/PROVEN_EVIDENCE_THRESHOLD
-// del scoring, pero es un criterio de negocio independiente (promoción
-// draft→active), no la reutilización semántica de "proven" — se declara
-// aparte para no acoplar accidentalmente ambos conceptos.
-const EVIDENCE_MIN_PROMOCION = 3;
-const CONTRADICTIONS_MIN_ARCHIVADO = 3;
-const CANDIDATO_GLOBAL_CONFIDENCE_MIN = 0.8;
-const CANDIDATO_GLOBAL_SOURCE_AGENTS_MIN = 2;
-const CANDIDATO_GLOBAL_SOURCE_SESSIONS_MIN = 3;
-
-function contadoresVacios() {
-  return {
-    promovidos: 0, degradados: 0, archivados: 0, candidatosGlobal: 0, sinCambios: 0,
-  };
-}
-
-/** Fecha local YYYY-MM-DD — NUNCA toISOString (gate C1 del proyecto). */
-function fechaLocal(ahora) {
-  const fecha = ahora instanceof Date ? ahora : new Date(ahora);
-  return fecha.toLocaleDateString('sv');
-}
-
-/** Copia superficial que preserva `__formato` (no enumerable, spread lo pierde). */
-function clonarConFormato(instinto) {
-  const copia = { ...instinto };
-  if (instinto.__formato) {
-    Object.defineProperty(copia, '__formato', {
-      value: instinto.__formato, enumerable: false, writable: true, configurable: true,
-    });
-  }
-  return copia;
-}
-
-/**
- * Decide la transición de status (b/c/d) según el status ORIGINAL del
- * instinto (antes de cualquier mutación de esta corrida).
- *
- * @returns {{status:string, deprecation_reason?:string}|null}
- */
-function evaluarTransicionEstado(instinto, recomputado, contadores) {
-  const evidenceCount = instinto.evidence_count || 0;
-
-  if (instinto.status === 'draft') {
-    const promociona = recomputado.effective_confidence >= ESTABLISHED_THRESHOLD
-      && evidenceCount >= EVIDENCE_MIN_PROMOCION;
-    if (!promociona) return null;
-    contadores.promovidos += 1;
-    return { status: 'active' };
-  }
-
-  if (instinto.status === 'degraded') {
-    if ((instinto.contradictions || 0) < CONTRADICTIONS_MIN_ARCHIVADO) return null;
-    contadores.archivados += 1;
-    return { status: 'archived' };
-  }
-
-  if (instinto.status !== 'archived' && shouldAutoDeprecate(instinto)) {
-    contadores.degradados += 1;
-    return { status: 'degraded', deprecation_reason: recomputado.deprecation_reason };
-  }
-
-  return null;
-}
-
-/** Candidato a promoción global: solo señala, nunca promueve por sí mismo. */
-function esCandidatoGlobal(instinto, effectiveConfidence) {
-  if (effectiveConfidence <= CANDIDATO_GLOBAL_CONFIDENCE_MIN) return false;
-  const agentes = (instinto.source_agents || []).length;
-  const sesiones = (instinto.source_sessions || []).length;
-  return agentes >= CANDIDATO_GLOBAL_SOURCE_AGENTS_MIN
-    || sesiones >= CANDIDATO_GLOBAL_SOURCE_SESSIONS_MIN;
-}
-
-/**
- * Aplica el ciclo completo de transición a un solo instinto.
- *
- * @returns {{instinto: object, mutado: boolean}}
- */
-function transicionarInstinto(instinto, ahora, contadores) {
-  const siguiente = clonarConFormato(instinto);
-  let mutado = false;
-
-  const recomputadoPrevio = recomputeStatus(instinto, ahora);
-  const transicion = evaluarTransicionEstado(instinto, recomputadoPrevio, contadores);
-  if (transicion) {
-    Object.assign(siguiente, transicion);
-    siguiente.last_validated = fechaLocal(ahora);
-    mutado = true;
-  }
-
-  const recomputadoFinal = recomputeStatus(siguiente, ahora);
-  if (siguiente.effective_confidence !== recomputadoFinal.effective_confidence) {
-    siguiente.effective_confidence = recomputadoFinal.effective_confidence;
-    mutado = true;
-  }
-  if (siguiente.maturity !== recomputadoFinal.maturity) {
-    siguiente.maturity = recomputadoFinal.maturity;
-    mutado = true;
-  }
-
-  if (esCandidatoGlobal(siguiente, recomputadoFinal.effective_confidence) && siguiente.candidato_global !== true) {
-    siguiente.candidato_global = true;
-    contadores.candidatosGlobal += 1;
-    mutado = true;
-  }
-
-  if (mutado) siguiente.origen = 'ciclo-autonomo';
-  else contadores.sinCambios += 1;
-
-  return { instinto: siguiente, mutado };
-}
-
-/**
- * Recomputa el scoring de cada instinto de `instintos/proyecto.yaml` y
- * persiste las transiciones de maduración. NUNCA borra instintos. Escribe
- * el archivo UNA sola vez, y solo si hubo al menos una mutación.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {{ahora?: Date}} [opciones]
- * @returns {{promovidos:number, degradados:number, archivados:number, candidatosGlobal:number, sinCambios:number}}
- */
-function aplicarTransiciones(baseDir, { ahora } = {}) {
-  const ruta = path.join(baseDir, RUTA_RELATIVA);
-  if (!fs.existsSync(ruta)) return contadoresVacios();
-
-  const momento = ahora || new Date();
-  const datos = leerInstintos(ruta);
-  const contadores = contadoresVacios();
-  let huboMutacion = false;
-
-  datos.instintos = datos.instintos.map((instinto) => {
-    const { instinto: siguiente, mutado } = transicionarInstinto(instinto, momento, contadores);
-    if (mutado) huboMutacion = true;
-    return siguiente;
-  });
-
-  if (huboMutacion) {
-    escribirInstintos(ruta, datos);
-  }
-
-  return contadores;
-}
-
-module.exports = { aplicarTransiciones };
+'use strict';
+
+/**
+ * writer-instintos.js — Aplica el scoring de `scoring-instintos.js` sobre
+ * `instintos/proyecto.yaml` y persiste las transiciones de maduración
+ * (Fase 21, T-04, REQ-21-01). Compone las funciones puras del scoring (que
+ * NUNCA persisten) con el round-trip de `yaml-instintos.js` (T-03).
+ *
+ * Decisión de mapeo de campo (ver CLAUDE.md / 21-PLAN.md "Inteligencia del
+ * codebase"): el YAML real usa `last_validated` (no `last_validated_at`).
+ * `scoring-instintos.getValidatedDate()` YA contempla ese nombre como
+ * fallback (`instinto.last_validated_at || instinto.last_validated || ...`),
+ * así que no se requiere ningún mapeo al leer — los instintos se pasan tal
+ * cual a `recomputeStatus`. Al refrescar la fecha de validación tras una
+ * transición de estado, este writer escribe `last_validated` (el campo real
+ * del schema), nunca `last_validated_at` (que es un campo interno del
+ * scoring usado solo por `applyFeedback`, ajeno al schema persistido aquí).
+ *
+ * Orden de cómputo por instinto (necesario para idempotencia, ver tests):
+ *   1. Recompute con el instinto ORIGINAL → decide si hay transición de
+ *      estado (b/c/d) usando el effective_confidence previo al refresh.
+ *   2. Si hubo transición, se refresca `last_validated` a `ahora`.
+ *   3. Recompute FINAL sobre el instinto ya transicionado (con la fecha de
+ *      validación definitiva) → ese valor es el que se persiste como
+ *      `effective_confidence`/`maturity`. Sin este segundo paso, una
+ *      segunda corrida con el mismo `ahora` recalcularía un decay distinto
+ *      (0 días desde el refresh) y rompería la idempotencia.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/writer-instintos
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  recomputeStatus,
+  shouldAutoDeprecate,
+  ESTABLISHED_THRESHOLD,
+} = require('../scoring-instintos');
+const { leerInstintos, escribirInstintos } = require('./yaml-instintos');
+
+/** Ruta relativa del YAML de instintos de proyecto dentro del baseDir. */
+const RUTA_RELATIVA = path.join('instintos', 'proyecto.yaml');
+
+// Mismo valor numérico que ESTABLISHED_THRESHOLD/PROVEN_EVIDENCE_THRESHOLD
+// del scoring, pero es un criterio de negocio independiente (promoción
+// draft→active), no la reutilización semántica de "proven" — se declara
+// aparte para no acoplar accidentalmente ambos conceptos.
+const EVIDENCE_MIN_PROMOCION = 3;
+const CONTRADICTIONS_MIN_ARCHIVADO = 3;
+const CANDIDATO_GLOBAL_CONFIDENCE_MIN = 0.8;
+const CANDIDATO_GLOBAL_SOURCE_AGENTS_MIN = 2;
+const CANDIDATO_GLOBAL_SOURCE_SESSIONS_MIN = 3;
+
+function contadoresVacios() {
+  return {
+    promovidos: 0, degradados: 0, archivados: 0, candidatosGlobal: 0, sinCambios: 0,
+  };
+}
+
+/** Fecha local YYYY-MM-DD — NUNCA toISOString (gate C1 del proyecto). */
+function fechaLocal(ahora) {
+  const fecha = ahora instanceof Date ? ahora : new Date(ahora);
+  return fecha.toLocaleDateString('sv');
+}
+
+/** Copia superficial que preserva `__formato` (no enumerable, spread lo pierde). */
+function clonarConFormato(instinto) {
+  const copia = { ...instinto };
+  if (instinto.__formato) {
+    Object.defineProperty(copia, '__formato', {
+      value: instinto.__formato, enumerable: false, writable: true, configurable: true,
+    });
+  }
+  return copia;
+}
+
+/**
+ * Decide la transición de status (b/c/d) según el status ORIGINAL del
+ * instinto (antes de cualquier mutación de esta corrida).
+ *
+ * @returns {{status:string, deprecation_reason?:string}|null}
+ */
+function evaluarTransicionEstado(instinto, recomputado, contadores) {
+  const evidenceCount = instinto.evidence_count || 0;
+
+  if (instinto.status === 'draft') {
+    const promociona = recomputado.effective_confidence >= ESTABLISHED_THRESHOLD
+      && evidenceCount >= EVIDENCE_MIN_PROMOCION;
+    if (!promociona) return null;
+    contadores.promovidos += 1;
+    return { status: 'active' };
+  }
+
+  if (instinto.status === 'degraded') {
+    if ((instinto.contradictions || 0) < CONTRADICTIONS_MIN_ARCHIVADO) return null;
+    contadores.archivados += 1;
+    return { status: 'archived' };
+  }
+
+  if (instinto.status !== 'archived' && shouldAutoDeprecate(instinto)) {
+    contadores.degradados += 1;
+    return { status: 'degraded', deprecation_reason: recomputado.deprecation_reason };
+  }
+
+  return null;
+}
+
+/** Candidato a promoción global: solo señala, nunca promueve por sí mismo. */
+function esCandidatoGlobal(instinto, effectiveConfidence) {
+  if (effectiveConfidence <= CANDIDATO_GLOBAL_CONFIDENCE_MIN) return false;
+  const agentes = (instinto.source_agents || []).length;
+  const sesiones = (instinto.source_sessions || []).length;
+  return agentes >= CANDIDATO_GLOBAL_SOURCE_AGENTS_MIN
+    || sesiones >= CANDIDATO_GLOBAL_SOURCE_SESSIONS_MIN;
+}
+
+/**
+ * Aplica el ciclo completo de transición a un solo instinto.
+ *
+ * @returns {{instinto: object, mutado: boolean}}
+ */
+function transicionarInstinto(instinto, ahora, contadores) {
+  const siguiente = clonarConFormato(instinto);
+  let mutado = false;
+
+  const recomputadoPrevio = recomputeStatus(instinto, ahora);
+  const transicion = evaluarTransicionEstado(instinto, recomputadoPrevio, contadores);
+  if (transicion) {
+    Object.assign(siguiente, transicion);
+    siguiente.last_validated = fechaLocal(ahora);
+    mutado = true;
+  }
+
+  const recomputadoFinal = recomputeStatus(siguiente, ahora);
+  if (siguiente.effective_confidence !== recomputadoFinal.effective_confidence) {
+    siguiente.effective_confidence = recomputadoFinal.effective_confidence;
+    mutado = true;
+  }
+  if (siguiente.maturity !== recomputadoFinal.maturity) {
+    siguiente.maturity = recomputadoFinal.maturity;
+    mutado = true;
+  }
+
+  if (esCandidatoGlobal(siguiente, recomputadoFinal.effective_confidence) && siguiente.candidato_global !== true) {
+    siguiente.candidato_global = true;
+    contadores.candidatosGlobal += 1;
+    mutado = true;
+  }
+
+  if (mutado) siguiente.origen = 'ciclo-autonomo';
+  else contadores.sinCambios += 1;
+
+  return { instinto: siguiente, mutado };
+}
+
+/**
+ * Recomputa el scoring de cada instinto de `instintos/proyecto.yaml` y
+ * persiste las transiciones de maduración. NUNCA borra instintos. Escribe
+ * el archivo UNA sola vez, y solo si hubo al menos una mutación.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{promovidos:number, degradados:number, archivados:number, candidatosGlobal:number, sinCambios:number}}
+ */
+function aplicarTransiciones(baseDir, { ahora } = {}) {
+  const ruta = path.join(baseDir, RUTA_RELATIVA);
+  if (!fs.existsSync(ruta)) return contadoresVacios();
+
+  const momento = ahora || new Date();
+  const datos = leerInstintos(ruta);
+  const contadores = contadoresVacios();
+  let huboMutacion = false;
+
+  datos.instintos = datos.instintos.map((instinto) => {
+    const { instinto: siguiente, mutado } = transicionarInstinto(instinto, momento, contadores);
+    if (mutado) huboMutacion = true;
+    return siguiente;
+  });
+
+  if (huboMutacion) {
+    escribirInstintos(ruta, datos);
+  }
+
+  return contadores;
+}
+
+module.exports = { aplicarTransiciones };