@saulwade/swl-ses 2.5.2 → 2.6.0

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

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

package/scripts/lib/ciclo-autonomo/runner-fase-b.js

@@ -0,0 +1,248 @@
+'use strict';
+
+/**
+ * runner-fase-b.js — Orquestador headless de la Fase B del ciclo autónomo
+ * (Fase 22, T-05, ADR-0042 gate G-B, REQ-22-04/REQ-22-05).
+ *
+ * Tubería secuencial de gates, cada uno con razón registrada (regla de
+ * negocio 5 — "toda corrida, incluso diferida, registra razón"): habilitado
+ * → lock propio (`.ciclo-fase-b-lock`) → catch-up (≥7 días desde
+ * `last_run_fase_b` Y candidatos pendientes) → guard de convivencia →
+ * credencial dual → presupuesto → tope de mutaciones por corrida →
+ * invocación (abstraída, F24). En `dryRun` (default `true`) el `invocador`
+ * NUNCA se llama — el runner valida la tubería completa y registra la
+ * corrida sin gastar ni invocar LLM.
+ *
+ * `invocador`, `detectorProcesos` y `verificadorCredencial` son interfaces
+ * INYECTABLES: F22 no implementa prompts/juez/mutación real (eso es F24);
+ * los tests inyectan dobles deterministas y verifican CERO spawns/llamadas
+ * reales al invocador.
+ *
+ * El gate de habilitado (1) es el ÚNICO que NO deja rastro en disco (ni
+ * lock ni telemetría) — Fase B apagada debe ser indistinguible de "nunca
+ * instalada". Todo gate posterior SIEMPRE appendea una línea a
+ * `evolution/ciclo-fase-b.jsonl`, incluida una corrida diferida.
+ *
+ * El marcador de "última corrida" de Fase B vive en `last_run_fase_b`
+ * (config), NO en el mtime del lockfile — por eso una corrida exitosa
+ * LIBERA el lock (lo borra) en vez de solo tocarle el mtime.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/runner-fase-b
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const config = require('./config');
+const candidatos = require('./candidatos');
+const guardConvivencia = require('./guard-convivencia');
+const presupuesto = require('./presupuesto');
+const { tryAcquireLock, rollbackLock, lockPath } = require('../../../hooks/lib/consolidation-lock');
+
+/** Lockfile propio de Fase B — independiente de `.ciclo-autonomo-lock` (Fase A). */
+const LOCK_FILENAME = '.ciclo-fase-b-lock';
+
+/** Ventana de catch-up: mínimo de días entre corridas reales de Fase B. */
+const CATCHUP_MS = 7 * 24 * 60 * 60 * 1000;
+
+const RUTA_TELEMETRIA_RELATIVA = path.join('evolution', 'ciclo-fase-b.jsonl');
+
+/** Razones de corte expuestas para consumo de tests/CLI (T-07 las imprime en `status`). */
+const RAZONES = Object.freeze({
+  DESHABILITADO: 'deshabilitado',
+  LOCK_OCUPADO: 'lock-ocupado',
+  SIN_CATCHUP: 'sin-catch-up',
+  SIN_CANDIDATOS: 'sin-candidatos',
+  CLAUDE_NO_EN_PATH: 'claude-no-en-path',
+  API_KEY_AUSENTE: 'api-key-ausente',
+  INVOCADOR_NO_DISPONIBLE: 'invocador-no-disponible',
+  INVOCADOR_FALLO: 'invocador-fallo',
+});
+
+function rutaTelemetria(baseDir) {
+  return path.join(baseDir, '.planning', RUTA_TELEMETRIA_RELATIVA);
+}
+
+/** Fecha-hora local legible ("YYYY-MM-DD HH:mm:ss") — NUNCA toISOString (gate C1). */
+function fechaHoraLocal(momento) {
+  return `${momento.toLocaleDateString('sv')} ${momento.toLocaleTimeString('sv')}`;
+}
+
+/** Append de una línea de telemetría a `evolution/ciclo-fase-b.jsonl`; crea el directorio si falta. */
+function escribirTelemetria(baseDir, entrada) {
+  const ruta = rutaTelemetria(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(ruta, JSON.stringify(entrada) + '\n');
+}
+
+/**
+ * `true` si ya pasaron >= 7 días desde `lastRunFaseB`. `null`/valor corrupto
+ * cuenta como catch-up debido (nunca hubo corrida real todavía).
+ */
+function tocaCatchUp(lastRunFaseB, ahora) {
+  if (!lastRunFaseB) return true;
+  const anterior = new Date(lastRunFaseB);
+  if (Number.isNaN(anterior.getTime())) return true;
+  return (ahora.getTime() - anterior.getTime()) >= CATCHUP_MS;
+}
+
+/** Detector de credencial por defecto (modo `cuenta`): `claude` resuelve en PATH. */
+function credencialCuentaPorDefecto() {
+  const resultado = spawnSync('claude', ['--version'], { timeout: 3000, encoding: 'utf8' });
+  return Boolean(resultado && !resultado.error && resultado.status === 0);
+}
+
+/**
+ * Verifica la credencial dual configurada. NUNCA lanza — cualquier fallo de
+ * detección se traduce a una razón accionable en vez de crashear el runner.
+ */
+function verificarCredencial(cfg, verificadorCredencial) {
+  if (cfg.credencial === 'api-key') {
+    const clave = process.env.ANTHROPIC_API_KEY;
+    if (!clave || clave.trim() === '') return { ok: false, razon: RAZONES.API_KEY_AUSENTE };
+    return { ok: true };
+  }
+
+  const verificar = verificadorCredencial || credencialCuentaPorDefecto;
+  let disponible = false;
+  try {
+    disponible = Boolean(verificar());
+  } catch (_) {
+    disponible = false;
+  }
+  return disponible ? { ok: true } : { ok: false, razon: RAZONES.CLAUDE_NO_EN_PATH };
+}
+
+/** Corte de una corrida diferida: rollback del lock adquirido + telemetría con la razón. */
+function diferir(baseDir, { momento, dryRun, priorMtime, razon, candidatosConsiderados = 0 }) {
+  rollbackLock(baseDir, priorMtime, { lockFilename: LOCK_FILENAME });
+  escribirTelemetria(baseDir, {
+    ts: momento.toISOString(),
+    origen: 'ciclo-fase-b',
+    dryRun,
+    razon,
+    candidatos_considerados: candidatosConsiderados,
+  });
+  return { ejecutado: false, razon };
+}
+
+/** Libera el lock de Fase B borrando el archivo (el marcador real es `last_run_fase_b`, no el mtime). */
+function liberarLock(baseDir) {
+  const lp = lockPath(baseDir, { lockFilename: LOCK_FILENAME });
+  try {
+    fs.unlinkSync(lp);
+  } catch (_) {
+    // ya no existía o no se pudo borrar — no bloqueante, la corrida ya completó.
+  }
+}
+
+/**
+ * Corre la Fase B headless sobre `baseDir`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{
+ *   ahora?: Date,
+ *   dryRun?: boolean,
+ *   invocador?: (candidatos: object[], ctx: {baseDir: string, ahora: Date}) => void,
+ *   detectorProcesos?: () => string,
+ *   verificadorCredencial?: () => boolean,
+ * }} [opciones]
+ * @returns {{ejecutado: boolean, razon?: string, dryRun?: boolean, candidatos?: number}}
+ */
+function correrFaseB(baseDir, {
+  ahora,
+  dryRun = true,
+  invocador,
+  detectorProcesos,
+  verificadorCredencial,
+} = {}) {
+  if (!config.estaFaseBHabilitada(baseDir)) {
+    return { ejecutado: false, razon: RAZONES.DESHABILITADO };
+  }
+
+  const momento = ahora || new Date();
+  const { acquired, priorMtime } = tryAcquireLock(baseDir, { lockFilename: LOCK_FILENAME });
+  if (!acquired) {
+    escribirTelemetria(baseDir, {
+      ts: momento.toISOString(),
+      origen: 'ciclo-fase-b',
+      dryRun,
+      razon: RAZONES.LOCK_OCUPADO,
+      candidatos_considerados: 0,
+    });
+    return { ejecutado: false, razon: RAZONES.LOCK_OCUPADO };
+  }
+
+  const cfg = config.leerConfig(baseDir);
+
+  if (!tocaCatchUp(cfg.last_run_fase_b, momento)) {
+    return diferir(baseDir, { momento, dryRun, priorMtime, razon: RAZONES.SIN_CATCHUP });
+  }
+
+  const deteccion = candidatos.detectar(baseDir, { ahora: momento });
+  if (deteccion.total === 0) {
+    return diferir(baseDir, { momento, dryRun, priorMtime, razon: RAZONES.SIN_CANDIDATOS });
+  }
+
+  const guard = guardConvivencia.evaluar({ detector: detectorProcesos });
+  if (guard.diferir) {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: guard.razon, candidatosConsiderados: deteccion.total,
+    });
+  }
+
+  const credencial = verificarCredencial(cfg, verificadorCredencial);
+  if (!credencial.ok) {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: credencial.razon, candidatosConsiderados: deteccion.total,
+    });
+  }
+
+  const gasto = presupuesto.puedeGastar(baseDir, 0, { ahora: momento });
+  if (!gasto.permitido) {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: gasto.razon, candidatosConsiderados: deteccion.total,
+    });
+  }
+
+  const candidatosAProcesar = deteccion.candidatos.slice(0, cfg.tope_mutaciones_corrida);
+
+  if (!dryRun && typeof invocador !== 'function') {
+    return diferir(baseDir, {
+      momento, dryRun, priorMtime, razon: RAZONES.INVOCADOR_NO_DISPONIBLE,
+      candidatosConsiderados: candidatosAProcesar.length,
+    });
+  }
+
+  if (!dryRun) {
+    try {
+      invocador(candidatosAProcesar, { baseDir, ahora: momento });
+    } catch (_) {
+      return diferir(baseDir, {
+        momento, dryRun, priorMtime, razon: RAZONES.INVOCADOR_FALLO,
+        candidatosConsiderados: candidatosAProcesar.length,
+      });
+    }
+  }
+
+  // dry-run feliz o corrida real exitosa: el catch-up se considera cumplido.
+  presupuesto.registrarGasto(baseDir, 0, { ahora: momento });
+  config.escribirConfig(baseDir, { last_run_fase_b: fechaHoraLocal(momento) });
+  liberarLock(baseDir);
+
+  escribirTelemetria(baseDir, {
+    ts: momento.toISOString(),
+    origen: 'ciclo-fase-b',
+    dryRun,
+    resultado: 'ok',
+    candidatos_considerados: candidatosAProcesar.length,
+  });
+
+  return { ejecutado: true, dryRun, candidatos: candidatosAProcesar.length };
+}
+
+module.exports = { correrFaseB, RAZONES };

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 };