@saulwade/swl-ses 2.5.3 → 2.6.0

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

@@ -0,0 +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 };