@saulwade/swl-ses 2.6.0 → 2.8.0

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

@@ -1,535 +1,591 @@
-'use strict';
-
-/**
- * yaml-instintos.js — Parser/serializador round-trip zero-deps de los YAML
- * de instintos (`instintos/proyecto.yaml`, `instintos/global.yaml`) y helper
- * mínimo de append para `instintos/perfil-usuario.yaml`.
- *
- * Fundacional de la Fase 21 (ADR-0041/0042, riesgo ALTO: corrupción de
- * memoria YAML). Extiende el patrón regex parcial de
- * `hooks/inyeccion-contexto.js` y `scripts/mcp-server/handlers.js` (que solo
- * LEEN pattern+confidence) a un round-trip campo-a-campo completo.
- *
- * NUNCA usar `js-yaml` ni ninguna dependencia de parsing YAML — zero-deps
- * absoluto (regla del proyecto). El formato soportado es el observado en el
- * repo: bloque de cabecera con campos escalares top-level, seguido de una
- * lista `instintos:` de entradas planas (2 niveles de indentación fijos:
- * `  - campo: valor` para el primer campo, `    campo: valor` para el resto,
- * y `      - item` para arreglos multilínea). No es un parser YAML genérico
- * — es intencionalmente acotado a esta estructura (simplicidad primero).
- *
- * @module scripts/lib/ciclo-autonomo/yaml-instintos
- */
-
-const fs = require('fs');
-const path = require('path');
-const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
-
-// ─────────────────────────────────────────────────────────────────────────
-// Utilidades de valor escalar (compartidas por header, instintos y perfil)
-// ─────────────────────────────────────────────────────────────────────────
-
-/**
- * Deshace el escapado mínimo (\" y \\) de un string entre comillas dobles.
- */
-function desescaparString(str) {
-  let out = '';
-  for (let i = 0; i < str.length; i++) {
-    if (str[i] === '\\' && i + 1 < str.length && (str[i + 1] === '"' || str[i + 1] === '\\')) {
-      out += str[i + 1];
-      i += 1;
-      continue;
-    }
-    out += str[i];
-  }
-  return out;
-}
-
-/** Escapa backslash y comillas dobles antes de envolver un string. */
-function escaparString(str) {
-  return String(str).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-}
-
-/**
- * Parsea un arreglo inline estilo `["a", "b"]` o `[1, 2]` respetando comillas.
- */
-function parsearArrayInline(str) {
-  const inner = str.slice(1, -1).trim();
-  if (inner === '') return [];
-
-  const items = [];
-  let actual = '';
-  let dentroComillas = false;
-  for (let i = 0; i < inner.length; i++) {
-    const c = inner[i];
-    if (c === '"') { dentroComillas = !dentroComillas; actual += c; continue; }
-    if (c === ',' && !dentroComillas) { items.push(actual.trim()); actual = ''; continue; }
-    actual += c;
-  }
-  if (actual.trim() !== '') items.push(actual.trim());
-
-  return items.map((it) => parsearValorInline(it).valor);
-}
-
-/**
- * Parsea el valor a la derecha de `clave:` en una sola línea.
- * Retorna `{ valor, tipo }` donde `tipo` guía la re-serialización exacta.
- * `tipo === 'vacio'` significa "sin valor en esta línea" — el llamador debe
- * esperar un bloque multilínea (`      - item`) en las líneas siguientes.
- */
-function parsearValorInline(raw) {
-  const str = raw.trim();
-  if (str === '') return { valor: undefined, tipo: 'vacio' };
-  if (str === 'null' || str === '~') return { valor: null, tipo: 'null' };
-  if (str === 'true' || str === 'false') return { valor: str === 'true', tipo: 'bool' };
-  if (/^\[[\s\S]*\]$/.test(str)) return { valor: parsearArrayInline(str), tipo: 'array-inline' };
-
-  const comillas = str.match(/^"([\s\S]*)"$/);
-  if (comillas) return { valor: desescaparString(comillas[1]), tipo: 'string-comillas' };
-
-  if (/^-?\d+(\.\d+)?$/.test(str)) {
-    return { valor: str.includes('.') ? parseFloat(str) : parseInt(str, 10), tipo: 'numero' };
-  }
-
-  return { valor: str, tipo: 'string-simple' };
-}
-
-/** Formatea un elemento de arreglo (nunca lleva metadata propia). */
-function formatearValorSimple(v) {
-  if (v === null || v === undefined) return 'null';
-  if (typeof v === 'boolean') return v ? 'true' : 'false';
-  if (typeof v === 'number') return String(v);
-  return `"${escaparString(v)}"`;
-}
-
-/** Infiere el tipo de formato para un valor sin metadata previa (campo nuevo). */
-function inferirFormato(valor) {
-  if (valor === null || valor === undefined) return { tipo: 'null' };
-  if (typeof valor === 'boolean') return { tipo: 'bool' };
-  if (typeof valor === 'number') return { tipo: 'numero' };
-  if (Array.isArray(valor)) return { tipo: 'array-inline' };
-  return { tipo: 'string-comillas' };
-}
-
-/**
- * Serializa un campo `clave: valor` (o bloque multilínea) con el indent dado.
- * Retorna un arreglo de líneas (1 para escalares/inline, N para multilínea).
- */
-function formatearLineaCampo(indent, clave, valor, info) {
-  const tipo = info && info.tipo;
-
-  if (tipo === 'array-multilinea') {
-    const lineas = [`${indent}${clave}:`];
-    const indentItem = ' '.repeat(indent.length + 2);
-    (valor || []).forEach((item) => lineas.push(`${indentItem}- ${formatearValorSimple(item)}`));
-    return lineas;
-  }
-  if (Array.isArray(valor)) {
-    const items = valor.map((v) => formatearValorSimple(v)).join(', ');
-    return [`${indent}${clave}: [${items}]`];
-  }
-  if (tipo === 'string-simple') return [`${indent}${clave}: ${valor}`];
-  if (tipo === 'numero') return [`${indent}${clave}: ${valor}`];
-  if (tipo === 'bool') return [`${indent}${clave}: ${valor ? 'true' : 'false'}`];
-  if (valor === null || valor === undefined || tipo === 'null') return [`${indent}${clave}: null`];
-
-  return [`${indent}${clave}: "${escaparString(valor)}"`];
-}
-
-/** Adjunta metadata de formato como propiedad NO enumerable (invisible a Object.keys/JSON). */
-function adjuntarFormato(obj, formato) {
-  Object.defineProperty(obj, '__formato', {
-    value: formato, enumerable: false, writable: true, configurable: true,
-  });
-  return obj;
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Header (campos escalares top-level antes de `instintos:`)
-// ─────────────────────────────────────────────────────────────────────────
-
-function parsearHeader(lineasHeader) {
-  const comentarios = [];
-  const campos = {};
-  const formato = {};
-  let vistoCampo = false;
-
-  lineasHeader.forEach((linea) => {
-    const trim = linea.trim();
-    if (trim === '') {
-      // Las líneas en blanco del preámbulo (antes del primer campo) son parte
-      // del formato original y sobreviven el round-trip (regresión T-13).
-      if (!vistoCampo) comentarios.push('');
-      return;
-    }
-    if (trim.startsWith('#')) {
-      if (!vistoCampo) comentarios.push(linea);
-      return;
-    }
-    const m = linea.match(/^([A-Za-z0-9_]+):\s?(.*)$/);
-    if (!m) return;
-    vistoCampo = true;
-    const [, clave, resto] = m;
-    const { valor, tipo } = parsearValorInline(resto);
-    campos[clave] = valor;
-    formato[clave] = { tipo };
-  });
-
-  adjuntarFormato(campos, formato);
-  return { comentarios, campos };
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Lista `instintos:` (entradas planas de 1 nivel + arreglos anidados)
-// ─────────────────────────────────────────────────────────────────────────
-
-function asignarCampo(objetivo, formato, clave, restoRaw) {
-  const { valor, tipo } = parsearValorInline(restoRaw);
-  if (tipo === 'vacio') {
-    objetivo[clave] = [];
-    formato[clave] = { tipo: 'array-multilinea' };
-    return clave; // señala que las siguientes líneas `- item` pertenecen a esta clave
-  }
-  objetivo[clave] = valor;
-  formato[clave] = { tipo };
-  return null;
-}
-
-function parsearListaInstintos(lineasBloque) {
-  const instintos = [];
-  let actual = null;
-  let formatoActual = null;
-  let campoMultilinea = null;
-
-  const cerrarActual = () => {
-    if (actual) instintos.push(adjuntarFormato(actual, formatoActual));
-  };
-
-  lineasBloque.forEach((linea) => {
-    if (linea.trim() === '') { campoMultilinea = null; return; }
-
-    const inicioItem = linea.match(/^ {2}- ([A-Za-z0-9_]+):\s?(.*)$/);
-    if (inicioItem) {
-      cerrarActual();
-      actual = {};
-      formatoActual = {};
-      campoMultilinea = asignarCampo(actual, formatoActual, inicioItem[1], inicioItem[2]);
-      return;
-    }
-
-    const campo = linea.match(/^ {4}([A-Za-z0-9_]+):\s?(.*)$/);
-    if (campo && actual) {
-      campoMultilinea = asignarCampo(actual, formatoActual, campo[1], campo[2]);
-      return;
-    }
-
-    const itemAnidado = linea.match(/^ {6}- (.*)$/);
-    if (itemAnidado && campoMultilinea) {
-      actual[campoMultilinea].push(parsearValorInline(itemAnidado[1]).valor);
-    }
-  });
-  cerrarActual();
-
-  return instintos;
-}
-
-function formatearInstinto(instinto) {
-  const meta = instinto.__formato || {};
-  const lineas = [];
-  Object.keys(instinto).forEach((clave, idx) => {
-    const valor = instinto[clave];
-    const info = meta[clave] || inferirFormato(valor);
-    const indent = idx === 0 ? '  - ' : '    ';
-    lineas.push(...formatearLineaCampo(indent, clave, valor, info));
-  });
-  return lineas;
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// API pública: leerInstintos / escribirInstintos / respaldar
-// ─────────────────────────────────────────────────────────────────────────
-
-/**
- * Lee un YAML de instintos (`proyecto.yaml` o `global.yaml`) y lo descompone
- * en `{ header, instintos }`. `header.campos` conserva el orden original de
- * inserción; cada instinto conserva TODOS sus campos (conocidos o no) más
- * una propiedad no-enumerable `__formato` con el estilo de serialización
- * observado (comillas, inline vs multilínea) para round-trip fiel.
- *
- * @param {string} rutaYaml - Ruta absoluta al archivo YAML.
- * @returns {{ header: { comentarios: string[], campos: object }, instintos: object[] }}
- */
-function leerInstintos(rutaYaml) {
-  const crudo = fs.readFileSync(rutaYaml, 'utf8');
-  const eol = crudo.includes('\r\n') ? '\r\n' : '\n';
-  const lineas = crudo.split(/\r\n|\n/);
-
-  const idxInline = lineas.findIndex((l) => /^instintos:\s*\[\]\s*$/.test(l));
-  const idxBloque = lineas.findIndex((l) => /^instintos:\s*$/.test(l));
-
-  let idxCorte;
-  let instintos;
-  if (idxBloque !== -1 && (idxInline === -1 || idxBloque < idxInline)) {
-    idxCorte = idxBloque;
-    instintos = parsearListaInstintos(lineas.slice(idxBloque + 1));
-  } else if (idxInline !== -1) {
-    idxCorte = idxInline;
-    instintos = [];
-  } else {
-    idxCorte = lineas.length;
-    instintos = [];
-  }
-
-  const header = parsearHeader(lineas.slice(0, idxCorte));
-  Object.defineProperty(header, '__eol', {
-    value: eol, enumerable: false, writable: true, configurable: true,
-  });
-
-  return { header, instintos };
-}
-
-/**
- * Copia `rutaYaml` a `instintos/.backups/<nombre>.<YYYY-MM-DD>-<HHmmss>.bak`
- * ANTES de cualquier escritura. No-op (retorna `null`) si el archivo destino
- * todavía no existe (nada que respaldar). Fecha local (`toLocaleDateString('sv')`
- * — nunca `toISOString()`, gate C1 del proyecto).
- *
- * @param {string} rutaYaml - Ruta absoluta del YAML a respaldar.
- * @returns {string|null} Ruta del backup creado, o `null` si no había nada que respaldar.
- */
-function respaldar(rutaYaml) {
-  if (!fs.existsSync(rutaYaml)) return null;
-
-  const backupDir = path.join(path.dirname(rutaYaml), '.backups');
-  if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });
-
-  const ahora = new Date();
-  const fecha = ahora.toLocaleDateString('sv'); // YYYY-MM-DD local — gate C1
-  const hhmmss = [ahora.getHours(), ahora.getMinutes(), ahora.getSeconds()]
-    .map((n) => String(n).padStart(2, '0')).join('');
-
-  const nombre = path.basename(rutaYaml);
-  let destino = path.join(backupDir, `${nombre}.${fecha}-${hhmmss}.bak`);
-  let sufijo = 1;
-  while (fs.existsSync(destino)) {
-    destino = path.join(backupDir, `${nombre}.${fecha}-${hhmmss}-${sufijo}.bak`);
-    sufijo += 1;
-  }
-
-  atomicWriteSync(destino, fs.readFileSync(rutaYaml, 'utf8'));
-  return destino;
-}
-
-/**
- * Serializa `{ header, instintos }` preservando el formato del repo
- * (indentación 2, comillas donde el original las usa, orden de campos
- * estable, listas inline o multilínea según metadata) y escribe con
- * `atomicWriteSync`. Respalda el archivo previo antes de escribir.
- * `total_instintos` se recalcula siempre a partir de `instintos.length`.
- *
- * @param {string} rutaYaml
- * @param {{ header: { comentarios?: string[], campos?: object, __eol?: string }, instintos: object[] }} datos
- */
-function escribirInstintos(rutaYaml, { header, instintos }) {
-  respaldar(rutaYaml);
-
-  const eol = (header && header.__eol) || '\n';
-  const comentarios = (header && header.comentarios) || [];
-  const campos = (header && header.campos) || {};
-  campos.total_instintos = instintos.length;
-
-  const formatoCampos = campos.__formato || {};
-  const lineas = [...comentarios];
-  Object.keys(campos).forEach((clave) => {
-    const valor = campos[clave];
-    const info = formatoCampos[clave] || inferirFormato(valor);
-    lineas.push(...formatearLineaCampo('', clave, valor, info));
-  });
-
-  lineas.push('');
-
-  if (instintos.length === 0) {
-    lineas.push('instintos: []');
-  } else {
-    lineas.push('instintos:');
-    instintos.forEach((instinto, idx) => {
-      if (idx > 0) lineas.push('');
-      lineas.push(...formatearInstinto(instinto));
-    });
-  }
-  lineas.push('');
-
-  atomicWriteSync(rutaYaml, lineas.join(eol));
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Helper mínimo de append para instintos/perfil-usuario.yaml
-// ─────────────────────────────────────────────────────────────────────────
-
-const SECCIONES_LISTA_ENTRADAS = [
-  'stack_preferido', 'patrones_trabajo', 'correcciones_repetidas', 'decisiones_validadas',
-];
-const SECCIONES_OBJETO = ['identidad', 'preferencias_comunicacion'];
-
-function finDeBloque(lineas, idxInicio) {
-  let fin = idxInicio + 1;
-  while (fin < lineas.length && (lineas[fin].trim() === '' || /^\s/.test(lineas[fin]))) fin += 1;
-  while (fin > idxInicio + 1 && lineas[fin - 1].trim() === '') fin -= 1;
-  return fin;
-}
-
-function formatearEntradaGenerica(entrada) {
-  return Object.keys(entrada).flatMap((clave, idx) => {
-    const valor = entrada[clave];
-    const indent = idx === 0 ? '  - ' : '    ';
-    return formatearLineaCampo(indent, clave, valor, inferirFormato(valor));
-  });
-}
-
-function insertarEnSeccionLista(lineas, seccion, entradas) {
-  const bloqueEntradas = entradas.flatMap((entrada, idx) => (
-    idx === 0 ? formatearEntradaGenerica(entrada) : ['', ...formatearEntradaGenerica(entrada)]
-  ));
-
-  const idxVacio = lineas.findIndex((l) => l.trim() === `${seccion}: []`);
-  if (idxVacio !== -1) {
-    const resultado = lineas.slice();
-    resultado.splice(idxVacio, 1, `${seccion}:`, ...bloqueEntradas);
-    return resultado;
-  }
-
-  const idxConEntradas = lineas.findIndex((l) => l.trim() === `${seccion}:`);
-  if (idxConEntradas === -1) {
-    throw new Error(`agregarSenalesPerfil: sección "${seccion}" no encontrada en el archivo`);
-  }
-  const fin = finDeBloque(lineas, idxConEntradas);
-  const resultado = lineas.slice();
-  resultado.splice(fin, 0, '', ...bloqueEntradas);
-  return resultado;
-}
-
-function mezclarSeccionObjeto(lineas, seccion, entradas) {
-  const idx = lineas.findIndex((l) => l.trim() === `${seccion}:`);
-  if (idx === -1) throw new Error(`agregarSenalesPerfil: sección "${seccion}" no encontrada`);
-  let fin = finDeBloque(lineas, idx);
-
-  let resultado = lineas.slice();
-  const patch = Object.assign({}, ...entradas);
-  Object.keys(patch).forEach((clave) => {
-    const valor = patch[clave];
-    const nuevaLinea = formatearLineaCampo('  ', clave, valor, inferirFormato(valor))[0];
-    const idxCampo = resultado.findIndex(
-      (l, i) => i > idx && i < fin && new RegExp(`^  ${clave}:`).test(l)
-    );
-    if (idxCampo !== -1) {
-      resultado[idxCampo] = nuevaLinea;
-    } else {
-      resultado.splice(fin, 0, nuevaLinea);
-      fin += 1;
-    }
-  });
-  return resultado;
-}
-
-function insertarEnArrayInline(lineas, rutaCampo, valores) {
-  const [padre, hijo] = rutaCampo.split('.');
-  const idxPadre = lineas.findIndex((l) => l.trim() === `${padre}:`);
-  if (idxPadre === -1) throw new Error(`agregarSenalesPerfil: sección "${padre}" no encontrada`);
-  const fin = finDeBloque(lineas, idxPadre);
-
-  const idxHijo = lineas.findIndex(
-    (l, i) => i > idxPadre && i < fin && new RegExp(`^\\s{2}${hijo}:\\s*\\[`).test(l)
-  );
-  if (idxHijo === -1) throw new Error(`agregarSenalesPerfil: campo "${hijo}" no encontrado en "${padre}"`);
-
-  const resultado = lineas.slice();
-  const linea = resultado[idxHijo];
-  const inicio = linea.indexOf('[');
-  const cierre = cierreDeArrayInline(linea, inicio);
-  if (cierre === -1) {
-    throw new Error(`agregarSenalesPerfil: array inline sin cierre en "${rutaCampo}"`);
-  }
-  // Solo el tramo [...] es el array; lo que sigue (típicamente un comentario
-  // YAML inline como `# Stacks/frameworks...`) se preserva intacto.
-  const actualStr = linea.slice(inicio, cierre + 1);
-  const sufijo = linea.slice(cierre + 1);
-  const combinado = parsearArrayInline(actualStr).concat(valores);
-  const items = combinado.map((v) => formatearValorSimple(v)).join(', ');
-  resultado[idxHijo] = `${linea.slice(0, inicio)}[${items}]${sufijo}`;
-  return resultado;
-}
-
-// Índice del `]` que cierra el array inline, ignorando corchetes dentro de
-// strings con comillas. -1 si la línea no cierra el array.
-function cierreDeArrayInline(linea, inicio) {
-  let dentroComillas = false;
-  for (let i = inicio; i < linea.length; i++) {
-    const c = linea[i];
-    if (c === '"') dentroComillas = !dentroComillas;
-    else if (c === ']' && !dentroComillas) return i;
-  }
-  return -1;
-}
-
-function actualizarCabeceraPerfil(lineas, incremento) {
-  const hoy = new Date().toLocaleDateString('sv');
-  return lineas.map((linea) => {
-    if (/^total_senales_consolidadas:\s*\d+\s*$/.test(linea)) {
-      const actual = parseInt(linea.match(/(\d+)/)[1], 10);
-      return `total_senales_consolidadas: ${actual + incremento}`;
-    }
-    if (/^actualizado:\s*"/.test(linea)) return `actualizado: "${hoy}"`;
-    return linea;
-  });
-}
-
-/**
- * Append mínimo de entradas draft a una sección de `perfil-usuario.yaml` sin
- * reescribir las secciones no tocadas. Actualiza `total_senales_consolidadas`
- * y `actualizado`. Respalda el archivo antes de escribir.
- *
- * Secciones soportadas:
- *   - Listas de entradas-objeto: `stack_preferido`, `patrones_trabajo`,
- *     `correcciones_repetidas`, `decisiones_validadas`. `entradas` es un
- *     arreglo de objetos planos `{campo: valor, ...}`.
- *   - Objetos de merge superficial: `identidad`, `preferencias_comunicacion`.
- *     `entradas` es un arreglo de parches `{campo: valor}` (el último gana).
- *   - Sub-listas inline de `limites_explicitos`: pasar `seccion` como
- *     `"limites_explicitos.no_guardar"` o `"limites_explicitos.no_sugerir"`;
- *     `entradas` es un arreglo de strings a anexar al arreglo inline.
- *
- * @param {string} rutaYaml
- * @param {string} seccion
- * @param {Array} entradas
- * @returns {{ agregadas: number }}
- */
-function agregarSenalesPerfil(rutaYaml, seccion, entradas) {
-  if (!Array.isArray(entradas) || entradas.length === 0) return { agregadas: 0 };
-
-  respaldar(rutaYaml);
-  const crudo = fs.readFileSync(rutaYaml, 'utf8');
-  const eol = crudo.includes('\r\n') ? '\r\n' : '\n';
-  const lineas = crudo.split(/\r\n|\n/);
-
-  let resultado;
-  if (SECCIONES_LISTA_ENTRADAS.includes(seccion)) {
-    resultado = insertarEnSeccionLista(lineas, seccion, entradas);
-  } else if (SECCIONES_OBJETO.includes(seccion)) {
-    resultado = mezclarSeccionObjeto(lineas, seccion, entradas);
-  } else if (seccion.startsWith('limites_explicitos.')) {
-    resultado = insertarEnArrayInline(lineas, seccion, entradas);
-  } else {
-    throw new Error(`agregarSenalesPerfil: sección desconocida "${seccion}"`);
-  }
-
-  resultado = actualizarCabeceraPerfil(resultado, entradas.length);
-  atomicWriteSync(rutaYaml, resultado.join(eol));
-  return { agregadas: entradas.length };
-}
-
-module.exports = {
-  leerInstintos,
-  escribirInstintos,
-  respaldar,
-  agregarSenalesPerfil,
-};
+'use strict';
+
+/**
+ * yaml-instintos.js — Parser/serializador round-trip zero-deps de los YAML
+ * de instintos (`instintos/proyecto.yaml`, `instintos/global.yaml`) y helper
+ * mínimo de append para `instintos/perfil-usuario.yaml`.
+ *
+ * Fundacional de la Fase 21 (ADR-0041/0042, riesgo ALTO: corrupción de
+ * memoria YAML). Extiende el patrón regex parcial de
+ * `hooks/inyeccion-contexto.js` y `scripts/mcp-server/handlers.js` (que solo
+ * LEEN pattern+confidence) a un round-trip campo-a-campo completo.
+ *
+ * NUNCA usar `js-yaml` ni ninguna dependencia de parsing YAML — zero-deps
+ * absoluto (regla del proyecto). El formato soportado es el observado en el
+ * repo: bloque de cabecera con campos escalares top-level, seguido de una
+ * lista `instintos:` de entradas planas (2 niveles de indentación fijos:
+ * `  - campo: valor` para el primer campo, `    campo: valor` para el resto,
+ * y `      - item` para arreglos multilínea). No es un parser YAML genérico
+ * — es intencionalmente acotado a esta estructura (simplicidad primero).
+ *
+ * @module scripts/lib/ciclo-autonomo/yaml-instintos
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+
+// ─────────────────────────────────────────────────────────────────────────
+// Utilidades de valor escalar (compartidas por header, instintos y perfil)
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Deshace el escapado mínimo (\" y \\) de un string entre comillas dobles.
+ */
+function desescaparString(str) {
+  let out = '';
+  for (let i = 0; i < str.length; i++) {
+    if (str[i] === '\\' && i + 1 < str.length && (str[i + 1] === '"' || str[i + 1] === '\\')) {
+      out += str[i + 1];
+      i += 1;
+      continue;
+    }
+    out += str[i];
+  }
+  return out;
+}
+
+/** Escapa backslash y comillas dobles antes de envolver un string. */
+function escaparString(str) {
+  return String(str).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Parsea un arreglo inline estilo `["a", "b"]` o `[1, 2]` respetando comillas.
+ */
+function parsearArrayInline(str) {
+  const inner = str.slice(1, -1).trim();
+  if (inner === '') return [];
+
+  const items = [];
+  let actual = '';
+  let dentroComillas = false;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    if (c === '"') { dentroComillas = !dentroComillas; actual += c; continue; }
+    if (c === ',' && !dentroComillas) { items.push(actual.trim()); actual = ''; continue; }
+    actual += c;
+  }
+  if (actual.trim() !== '') items.push(actual.trim());
+
+  return items.map((it) => parsearValorInline(it).valor);
+}
+
+/**
+ * Parsea el valor a la derecha de `clave:` en una sola línea.
+ * Retorna `{ valor, tipo }` donde `tipo` guía la re-serialización exacta.
+ * `tipo === 'vacio'` significa "sin valor en esta línea" — el llamador debe
+ * esperar un bloque multilínea (`      - item`) en las líneas siguientes.
+ */
+function parsearValorInline(raw) {
+  const str = raw.trim();
+  if (str === '') return { valor: undefined, tipo: 'vacio' };
+  if (str === 'null' || str === '~') return { valor: null, tipo: 'null' };
+  if (str === 'true' || str === 'false') return { valor: str === 'true', tipo: 'bool' };
+  if (/^\[[\s\S]*\]$/.test(str)) return { valor: parsearArrayInline(str), tipo: 'array-inline' };
+
+  const comillas = str.match(/^"([\s\S]*)"$/);
+  if (comillas) return { valor: desescaparString(comillas[1]), tipo: 'string-comillas' };
+
+  if (/^-?\d+(\.\d+)?$/.test(str)) {
+    return { valor: str.includes('.') ? parseFloat(str) : parseInt(str, 10), tipo: 'numero' };
+  }
+
+  return { valor: str, tipo: 'string-simple' };
+}
+
+/** Formatea un elemento de arreglo (nunca lleva metadata propia). */
+function formatearValorSimple(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') return String(v);
+  return `"${escaparString(v)}"`;
+}
+
+/** Infiere el tipo de formato para un valor sin metadata previa (campo nuevo). */
+function inferirFormato(valor) {
+  if (valor === null || valor === undefined) return { tipo: 'null' };
+  if (typeof valor === 'boolean') return { tipo: 'bool' };
+  if (typeof valor === 'number') return { tipo: 'numero' };
+  if (Array.isArray(valor)) return { tipo: 'array-inline' };
+  return { tipo: 'string-comillas' };
+}
+
+/**
+ * Serializa un campo `clave: valor` (o bloque multilínea) con el indent dado.
+ * Retorna un arreglo de líneas (1 para escalares/inline, N para multilínea).
+ */
+function formatearLineaCampo(indent, clave, valor, info) {
+  const tipo = info && info.tipo;
+
+  if (tipo === 'array-multilinea') {
+    const lineas = [`${indent}${clave}:`];
+    const indentItem = ' '.repeat(indent.length + 2);
+    (valor || []).forEach((item) => lineas.push(`${indentItem}- ${formatearValorSimple(item)}`));
+    return lineas;
+  }
+  if (Array.isArray(valor)) {
+    const items = valor.map((v) => formatearValorSimple(v)).join(', ');
+    return [`${indent}${clave}: [${items}]`];
+  }
+  if (tipo === 'string-simple') return [`${indent}${clave}: ${valor}`];
+  if (tipo === 'numero') return [`${indent}${clave}: ${valor}`];
+  if (tipo === 'bool') return [`${indent}${clave}: ${valor ? 'true' : 'false'}`];
+  if (valor === null || valor === undefined || tipo === 'null') return [`${indent}${clave}: null`];
+
+  return [`${indent}${clave}: "${escaparString(valor)}"`];
+}
+
+/** Adjunta metadata de formato como propiedad NO enumerable (invisible a Object.keys/JSON). */
+function adjuntarFormato(obj, formato) {
+  Object.defineProperty(obj, '__formato', {
+    value: formato, enumerable: false, writable: true, configurable: true,
+  });
+  return obj;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Header (campos escalares top-level antes de `instintos:`)
+// ─────────────────────────────────────────────────────────────────────────
+
+function parsearHeader(lineasHeader) {
+  const comentarios = [];
+  const campos = {};
+  const formato = {};
+  let vistoCampo = false;
+
+  lineasHeader.forEach((linea) => {
+    const trim = linea.trim();
+    if (trim === '') {
+      // Las líneas en blanco del preámbulo (antes del primer campo) son parte
+      // del formato original y sobreviven el round-trip (regresión T-13).
+      if (!vistoCampo) comentarios.push('');
+      return;
+    }
+    if (trim.startsWith('#')) {
+      if (!vistoCampo) comentarios.push(linea);
+      return;
+    }
+    const m = linea.match(/^([A-Za-z0-9_]+):\s?(.*)$/);
+    if (!m) return;
+    vistoCampo = true;
+    const [, clave, resto] = m;
+    const { valor, tipo } = parsearValorInline(resto);
+    campos[clave] = valor;
+    formato[clave] = { tipo };
+  });
+
+  adjuntarFormato(campos, formato);
+  return { comentarios, campos };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Lista `instintos:` (entradas planas de 1 nivel + arreglos anidados)
+// ─────────────────────────────────────────────────────────────────────────
+
+function asignarCampo(objetivo, formato, clave, restoRaw) {
+  const { valor, tipo } = parsearValorInline(restoRaw);
+  if (tipo === 'vacio') {
+    objetivo[clave] = [];
+    formato[clave] = { tipo: 'array-multilinea' };
+    return clave; // señala que las siguientes líneas `- item` pertenecen a esta clave
+  }
+  objetivo[clave] = valor;
+  formato[clave] = { tipo };
+  return null;
+}
+
+function parsearListaInstintos(lineasBloque) {
+  const instintos = [];
+  let actual = null;
+  let formatoActual = null;
+  let campoMultilinea = null;
+
+  const cerrarActual = () => {
+    if (actual) instintos.push(adjuntarFormato(actual, formatoActual));
+  };
+
+  lineasBloque.forEach((linea) => {
+    if (linea.trim() === '') { campoMultilinea = null; return; }
+
+    const inicioItem = linea.match(/^ {2}- ([A-Za-z0-9_]+):\s?(.*)$/);
+    if (inicioItem) {
+      cerrarActual();
+      actual = {};
+      formatoActual = {};
+      campoMultilinea = asignarCampo(actual, formatoActual, inicioItem[1], inicioItem[2]);
+      return;
+    }
+
+    const campo = linea.match(/^ {4}([A-Za-z0-9_]+):\s?(.*)$/);
+    if (campo && actual) {
+      campoMultilinea = asignarCampo(actual, formatoActual, campo[1], campo[2]);
+      return;
+    }
+
+    const itemAnidado = linea.match(/^ {6}- (.*)$/);
+    if (itemAnidado && campoMultilinea) {
+      actual[campoMultilinea].push(parsearValorInline(itemAnidado[1]).valor);
+    }
+  });
+  cerrarActual();
+
+  return instintos;
+}
+
+function formatearInstinto(instinto) {
+  const meta = instinto.__formato || {};
+  const lineas = [];
+  Object.keys(instinto).forEach((clave, idx) => {
+    const valor = instinto[clave];
+    const info = meta[clave] || inferirFormato(valor);
+    const indent = idx === 0 ? '  - ' : '    ';
+    lineas.push(...formatearLineaCampo(indent, clave, valor, info));
+  });
+  return lineas;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// API pública: leerInstintos / escribirInstintos / respaldar
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Lee un YAML de instintos (`proyecto.yaml` o `global.yaml`) y lo descompone
+ * en `{ header, instintos }`. `header.campos` conserva el orden original de
+ * inserción; cada instinto conserva TODOS sus campos (conocidos o no) más
+ * una propiedad no-enumerable `__formato` con el estilo de serialización
+ * observado (comillas, inline vs multilínea) para round-trip fiel.
+ *
+ * @param {string} rutaYaml - Ruta absoluta al archivo YAML.
+ * @returns {{ header: { comentarios: string[], campos: object }, instintos: object[] }}
+ */
+function leerInstintos(rutaYaml) {
+  const crudo = fs.readFileSync(rutaYaml, 'utf8');
+  const eol = crudo.includes('\r\n') ? '\r\n' : '\n';
+  const lineas = crudo.split(/\r\n|\n/);
+
+  const idxInline = lineas.findIndex((l) => /^instintos:\s*\[\]\s*$/.test(l));
+  const idxBloque = lineas.findIndex((l) => /^instintos:\s*$/.test(l));
+
+  let idxCorte;
+  let instintos;
+  if (idxBloque !== -1 && (idxInline === -1 || idxBloque < idxInline)) {
+    idxCorte = idxBloque;
+    instintos = parsearListaInstintos(lineas.slice(idxBloque + 1));
+  } else if (idxInline !== -1) {
+    idxCorte = idxInline;
+    instintos = [];
+  } else {
+    idxCorte = lineas.length;
+    instintos = [];
+  }
+
+  const header = parsearHeader(lineas.slice(0, idxCorte));
+  Object.defineProperty(header, '__eol', {
+    value: eol, enumerable: false, writable: true, configurable: true,
+  });
+
+  return { header, instintos };
+}
+
+/**
+ * Copia `rutaYaml` a `instintos/.backups/<nombre>.<YYYY-MM-DD>-<HHmmss>.bak`
+ * ANTES de cualquier escritura. No-op (retorna `null`) si el archivo destino
+ * todavía no existe (nada que respaldar). Fecha local (`toLocaleDateString('sv')`
+ * — nunca `toISOString()`, gate C1 del proyecto).
+ *
+ * @param {string} rutaYaml - Ruta absoluta del YAML a respaldar.
+ * @returns {string|null} Ruta del backup creado, o `null` si no había nada que respaldar.
+ */
+function respaldar(rutaYaml) {
+  if (!fs.existsSync(rutaYaml)) return null;
+
+  const backupDir = path.join(path.dirname(rutaYaml), '.backups');
+  if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });
+
+  const ahora = new Date();
+  const fecha = ahora.toLocaleDateString('sv'); // YYYY-MM-DD local — gate C1
+  const hhmmss = [ahora.getHours(), ahora.getMinutes(), ahora.getSeconds()]
+    .map((n) => String(n).padStart(2, '0')).join('');
+
+  const nombre = path.basename(rutaYaml);
+  let destino = path.join(backupDir, `${nombre}.${fecha}-${hhmmss}.bak`);
+  let sufijo = 1;
+  while (fs.existsSync(destino)) {
+    destino = path.join(backupDir, `${nombre}.${fecha}-${hhmmss}-${sufijo}.bak`);
+    sufijo += 1;
+  }
+
+  atomicWriteSync(destino, fs.readFileSync(rutaYaml, 'utf8'));
+  return destino;
+}
+
+/**
+ * Serializa `{ header, instintos }` preservando el formato del repo
+ * (indentación 2, comillas donde el original las usa, orden de campos
+ * estable, listas inline o multilínea según metadata) y escribe con
+ * `atomicWriteSync`. Respalda el archivo previo antes de escribir.
+ * `total_instintos` se recalcula siempre a partir de `instintos.length`.
+ *
+ * @param {string} rutaYaml
+ * @param {{ header: { comentarios?: string[], campos?: object, __eol?: string }, instintos: object[] }} datos
+ */
+function escribirInstintos(rutaYaml, { header, instintos }) {
+  respaldar(rutaYaml);
+
+  const eol = (header && header.__eol) || '\n';
+  const comentarios = (header && header.comentarios) || [];
+  const campos = (header && header.campos) || {};
+  campos.total_instintos = instintos.length;
+
+  const formatoCampos = campos.__formato || {};
+  const lineas = [...comentarios];
+  Object.keys(campos).forEach((clave) => {
+    const valor = campos[clave];
+    const info = formatoCampos[clave] || inferirFormato(valor);
+    lineas.push(...formatearLineaCampo('', clave, valor, info));
+  });
+
+  lineas.push('');
+
+  if (instintos.length === 0) {
+    lineas.push('instintos: []');
+  } else {
+    lineas.push('instintos:');
+    instintos.forEach((instinto, idx) => {
+      if (idx > 0) lineas.push('');
+      lineas.push(...formatearInstinto(instinto));
+    });
+  }
+  lineas.push('');
+
+  atomicWriteSync(rutaYaml, lineas.join(eol));
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Helper mínimo de append para instintos/perfil-usuario.yaml
+// ─────────────────────────────────────────────────────────────────────────
+
+const SECCIONES_LISTA_ENTRADAS = [
+  'stack_preferido', 'patrones_trabajo', 'correcciones_repetidas', 'decisiones_validadas',
+];
+const SECCIONES_OBJETO = ['identidad', 'preferencias_comunicacion'];
+
+function finDeBloque(lineas, idxInicio) {
+  let fin = idxInicio + 1;
+  while (fin < lineas.length && (lineas[fin].trim() === '' || /^\s/.test(lineas[fin]))) fin += 1;
+  while (fin > idxInicio + 1 && lineas[fin - 1].trim() === '') fin -= 1;
+  return fin;
+}
+
+function formatearEntradaGenerica(entrada) {
+  return Object.keys(entrada).flatMap((clave, idx) => {
+    const valor = entrada[clave];
+    const indent = idx === 0 ? '  - ' : '    ';
+    return formatearLineaCampo(indent, clave, valor, inferirFormato(valor));
+  });
+}
+
+function insertarEnSeccionLista(lineas, seccion, entradas) {
+  const bloqueEntradas = entradas.flatMap((entrada, idx) => (
+    idx === 0 ? formatearEntradaGenerica(entrada) : ['', ...formatearEntradaGenerica(entrada)]
+  ));
+
+  const idxVacio = lineas.findIndex((l) => l.trim() === `${seccion}: []`);
+  if (idxVacio !== -1) {
+    const resultado = lineas.slice();
+    resultado.splice(idxVacio, 1, `${seccion}:`, ...bloqueEntradas);
+    return resultado;
+  }
+
+  const idxConEntradas = lineas.findIndex((l) => l.trim() === `${seccion}:`);
+  if (idxConEntradas === -1) {
+    throw new Error(`agregarSenalesPerfil: sección "${seccion}" no encontrada en el archivo`);
+  }
+  const fin = finDeBloque(lineas, idxConEntradas);
+  const resultado = lineas.slice();
+  resultado.splice(fin, 0, '', ...bloqueEntradas);
+  return resultado;
+}
+
+function mezclarSeccionObjeto(lineas, seccion, entradas) {
+  const idx = lineas.findIndex((l) => l.trim() === `${seccion}:`);
+  if (idx === -1) throw new Error(`agregarSenalesPerfil: sección "${seccion}" no encontrada`);
+  let fin = finDeBloque(lineas, idx);
+
+  let resultado = lineas.slice();
+  const patch = Object.assign({}, ...entradas);
+  Object.keys(patch).forEach((clave) => {
+    const valor = patch[clave];
+    const nuevaLinea = formatearLineaCampo('  ', clave, valor, inferirFormato(valor))[0];
+    const idxCampo = resultado.findIndex(
+      (l, i) => i > idx && i < fin && new RegExp(`^  ${clave}:`).test(l)
+    );
+    if (idxCampo !== -1) {
+      resultado[idxCampo] = nuevaLinea;
+    } else {
+      resultado.splice(fin, 0, nuevaLinea);
+      fin += 1;
+    }
+  });
+  return resultado;
+}
+
+function insertarEnArrayInline(lineas, rutaCampo, valores) {
+  const [padre, hijo] = rutaCampo.split('.');
+  const idxPadre = lineas.findIndex((l) => l.trim() === `${padre}:`);
+  if (idxPadre === -1) throw new Error(`agregarSenalesPerfil: sección "${padre}" no encontrada`);
+  const fin = finDeBloque(lineas, idxPadre);
+
+  const idxHijo = lineas.findIndex(
+    (l, i) => i > idxPadre && i < fin && new RegExp(`^\\s{2}${hijo}:\\s*\\[`).test(l)
+  );
+  if (idxHijo === -1) throw new Error(`agregarSenalesPerfil: campo "${hijo}" no encontrado en "${padre}"`);
+
+  const resultado = lineas.slice();
+  const linea = resultado[idxHijo];
+  const inicio = linea.indexOf('[');
+  const cierre = cierreDeArrayInline(linea, inicio);
+  if (cierre === -1) {
+    throw new Error(`agregarSenalesPerfil: array inline sin cierre en "${rutaCampo}"`);
+  }
+  // Solo el tramo [...] es el array; lo que sigue (típicamente un comentario
+  // YAML inline como `# Stacks/frameworks...`) se preserva intacto.
+  const actualStr = linea.slice(inicio, cierre + 1);
+  const sufijo = linea.slice(cierre + 1);
+  const combinado = parsearArrayInline(actualStr).concat(valores);
+  const items = combinado.map((v) => formatearValorSimple(v)).join(', ');
+  resultado[idxHijo] = `${linea.slice(0, inicio)}[${items}]${sufijo}`;
+  return resultado;
+}
+
+// Índice del `]` que cierra el array inline, ignorando corchetes dentro de
+// strings con comillas. -1 si la línea no cierra el array.
+function cierreDeArrayInline(linea, inicio) {
+  let dentroComillas = false;
+  for (let i = inicio; i < linea.length; i++) {
+    const c = linea[i];
+    if (c === '"') dentroComillas = !dentroComillas;
+    else if (c === ']' && !dentroComillas) return i;
+  }
+  return -1;
+}
+
+function actualizarCabeceraPerfil(lineas, incremento) {
+  const hoy = new Date().toLocaleDateString('sv');
+  return lineas.map((linea) => {
+    if (/^total_senales_consolidadas:\s*\d+\s*$/.test(linea)) {
+      const actual = parseInt(linea.match(/(\d+)/)[1], 10);
+      return `total_senales_consolidadas: ${actual + incremento}`;
+    }
+    if (/^actualizado:\s*"/.test(linea)) return `actualizado: "${hoy}"`;
+    return linea;
+  });
+}
+
+/**
+ * Plantilla canónica de `perfil-usuario.yaml` para proyectos que instalaron
+ * SWL antes de la Fase 21 (ADR-0041/0042) y nunca tuvieron este archivo.
+ * Debe mantenerse en sync con `agentes/perfilador-usuario-swl.md` y con el
+ * fixture congelado `tests/ciclo-autonomo/fixtures/perfil-usuario.yaml`.
+ */
+function plantillaPerfilUsuario() {
+  const hoy = new Date().toLocaleDateString('sv');
+  return [
+    '# Perfil de Usuario — Modelo persistente entre sesiones',
+    '# Generado y mantenido por agentes/perfilador-usuario-swl.md',
+    '# Alimentado por hooks/actualizar-perfil-usuario.js (acumula señales en .planning/perfil-usuario/dirty.json)',
+    '# NUNCA editar a mano datos con confidence >= 0.9 sin contraevidencia documentada',
+    '# Formato estandarizado v1.0',
+    '',
+    'version: "1.0"',
+    `generado: "${hoy}"`,
+    `actualizado: "${hoy}"`,
+    'total_senales_consolidadas: 0',
+    '',
+    'identidad:',
+    '  rol: null',
+    '  rol_confidence: 0.0',
+    '  rol_fuentes: []',
+    '  anos_experiencia: null',
+    '  zonas_horarias_activas: []',
+    '',
+    'stack_preferido: []',
+    '',
+    'patrones_trabajo: []',
+    '',
+    'correcciones_repetidas: []',
+    '',
+    'decisiones_validadas: []',
+    '',
+    'preferencias_comunicacion:',
+    '  idioma: "es-MX"',
+    '  formalidad: null',
+    '  longitud_respuestas: null',
+    '  detalle_explicaciones: null',
+    '  confirmacion_acciones: null',
+    '',
+    'limites_explicitos:',
+    '  no_guardar: []',
+    '  no_sugerir: []',
+    '',
+  ].join(String.fromCharCode(10));
+}
+
+/**
+ * Append mínimo de entradas draft a una sección de `perfil-usuario.yaml` sin
+ * reescribir las secciones no tocadas. Actualiza `total_senales_consolidadas`
+ * y `actualizado`. Respalda el archivo antes de escribir.
+ *
+ * Secciones soportadas:
+ *   - Listas de entradas-objeto: `stack_preferido`, `patrones_trabajo`,
+ *     `correcciones_repetidas`, `decisiones_validadas`. `entradas` es un
+ *     arreglo de objetos planos `{campo: valor, ...}`.
+ *   - Objetos de merge superficial: `identidad`, `preferencias_comunicacion`.
+ *     `entradas` es un arreglo de parches `{campo: valor}` (el último gana).
+ *   - Sub-listas inline de `limites_explicitos`: pasar `seccion` como
+ *     `"limites_explicitos.no_guardar"` o `"limites_explicitos.no_sugerir"`;
+ *     `entradas` es un arreglo de strings a anexar al arreglo inline.
+ *
+ * @param {string} rutaYaml
+ * @param {string} seccion
+ * @param {Array} entradas
+ * @returns {{ agregadas: number }}
+ */
+function agregarSenalesPerfil(rutaYaml, seccion, entradas) {
+  if (!Array.isArray(entradas) || entradas.length === 0) return { agregadas: 0 };
+
+  if (!fs.existsSync(rutaYaml)) {
+    const dir = path.dirname(rutaYaml);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    atomicWriteSync(rutaYaml, plantillaPerfilUsuario());
+  }
+
+  respaldar(rutaYaml);
+  const crudo = fs.readFileSync(rutaYaml, 'utf8');
+  const eol = crudo.includes('\r\n') ? '\r\n' : '\n';
+  const lineas = crudo.split(/\r\n|\n/);
+
+  let resultado;
+  if (SECCIONES_LISTA_ENTRADAS.includes(seccion)) {
+    resultado = insertarEnSeccionLista(lineas, seccion, entradas);
+  } else if (SECCIONES_OBJETO.includes(seccion)) {
+    resultado = mezclarSeccionObjeto(lineas, seccion, entradas);
+  } else if (seccion.startsWith('limites_explicitos.')) {
+    resultado = insertarEnArrayInline(lineas, seccion, entradas);
+  } else {
+    throw new Error(`agregarSenalesPerfil: sección desconocida "${seccion}"`);
+  }
+
+  resultado = actualizarCabeceraPerfil(resultado, entradas.length);
+  atomicWriteSync(rutaYaml, resultado.join(eol));
+  return { agregadas: entradas.length };
+}
+
+module.exports = {
+  leerInstintos,
+  escribirInstintos,
+  respaldar,
+  agregarSenalesPerfil,
+  plantillaPerfilUsuario,
+};