@saulwade/swl-ses 2.2.0 → 2.2.1

package/scripts/instalador.js

@@ -36,6 +36,8 @@ const {
   mergeEvolved,
   scanEvolved,
 } = require('../hooks/lib/evolution-tracker');
+const { canonicalHash } = require('./lib/canonical-hash');
+const { auditarEscritura } = require('./lib/audit-evolved');
 const { detectarStack, filtrarReglasPorStack } = require('./lib/detectar-stack');
 const { actualizarGitignore, entradasParaRuntime, limpiarTracked, leerManifest, escribirManifest } = require('./lib/gitignore-manifest');
 
@@ -575,24 +577,12 @@ async function install(opciones) {
       }
       console.log('');
 
-      // FIX v1.6.6: avisar al usuario cuando el target copia habilidades como
-      // directorio completo (Cursor, Codex). Ese path no pasa por
-      // decideUpdateStrategy a nivel de SKILL.md, así que las evoluciones se
-      // sobreescriben silenciosamente. Cierre completo del gap = DT-EVOL-DIR
-      // documentado en .planning/DEUDA-TECNICA.md.
-      const targetCopiaDirectorios = ['cursor', 'codex'].includes(target);
-      const tieneSkillEvolucionado = evolved.some((e) => path.basename(e.path) === 'SKILL.md');
-      if (targetCopiaDirectorios && tieneSkillEvolucionado) {
-        console.log(
-          `  ⚠ Aviso: en target "${target}" las habilidades se copian como directorio. Las ` +
-          `evoluciones de SKILL.md serán sobreescritas. Backup de seguridad creado en ` +
-          `.planning/backups/v${versionAnterior || 'previa'}/.`
-        );
-        console.log(
-          '    (Ver DT-EVOL-DIR en .planning/DEUDA-TECNICA.md para el plan de cierre.)'
-        );
-        console.log('');
-      }
+      // Fase 16 (REQ-16-09, cierra DT-EVOL-DIR): el path de habilidades —incluido
+      // cursor/codex que copian el directorio completo— ahora pasa por el
+      // discriminador A/B a nivel de SKILL.md en instalarArchivo: la evolución
+      // del usuario (A) se preserva (merge + diff) y solo los recursos se
+      // actualizan; shipped-evolved (B) se actualiza con backup + auditoría. Ya
+      // NO hay sobreescritura silenciosa de SKILL.md evolucionado.
     }
   }
 
@@ -1166,47 +1156,121 @@ function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
     return { instalado: false, protegido: true };
   }
 
-  // Evolución: Verificar si el destino fue evolucionado por auto-evolución
+  // Evolución (Fase 16): decidir estrategia para componentes evolved SIN exigir
+  // --force. El discriminador A/B garantiza el invariante: A (evolución del
+  // usuario) → merge (preserve + diff), JAMÁS overwrite; B (shipped-evolved
+  // intacto, hash baseline coincide) → overwrite con backup + auditoría.
   const esComponenteEvolucionable = ['agentes', 'habilidades', 'comandos', 'reglas'].includes(archivo.tipo);
-  if (esComponenteEvolucionable && fs.existsSync(destino) && opciones.force) {
-    // Resolver ruta absoluta del origen (archivo.origen es relativo al paquete)
+  let forzarEscrituraEvolved = false;
+  if (esComponenteEvolucionable && fs.existsSync(destino)) {
     const origenAbsoluto = path.resolve(RAIZ_PKG, archivo.origen);
-    const strategy = decideUpdateStrategy(destino, origenAbsoluto, opciones.versionActual || '');
-    if (strategy.strategy === 'preserve') {
-      console.log(`  ★ Evolucionado: ${nombreArchivo} — preservado (${strategy.reason})`);
-      return { instalado: false, evolucionado: true, destino };
+    // Las habilidades son DIRECTORIOS: la marca evolved vive en su SKILL.md.
+    // Discriminar sobre el SKILL.md interno, no sobre el directorio (REQ-16-09,
+    // cierra DT-EVOL-DIR — cursor/codex copiaban el dir completo y pisaban la
+    // evolución del usuario).
+    const esDirSkill = archivo.tipo === 'habilidades';
+    const cmpDestino = esDirSkill ? path.join(destino, 'SKILL.md') : destino;
+    const cmpOrigen  = esDirSkill ? path.join(origenAbsoluto, 'SKILL.md') : origenAbsoluto;
+    const versionBackup = opciones.versionAnterior || opciones.versionActual || 'previa';
+
+    // MEDIO (nemesis O6): dir de skill existe pero sin SKILL.md = instalación
+    // corrupta. Diagnóstico explícito (cae al flujo normal, no rompe invariante).
+    if (esDirSkill && !fs.existsSync(cmpDestino)) {
+      console.log(`  ! Skill ${nombreArchivo}: directorio existe pero SKILL.md faltante — instalación incompleta; usa --force para reparar`);
     }
-    if (strategy.strategy === 'conflict') {
-      // Crear backup del archivo evolucionado ANTES de sobrescribir
-      if (opciones.versionAnterior) {
-        const backup = crearBackup(process.cwd(), destino, opciones.versionAnterior);
-        if (backup.respaldado) {
-          console.log(`  ⚠ Conflicto: ${nombreArchivo} — evolucionado localmente + cambios en versión nueva`);
-          console.log(`    ↩ Backup evolucionado: ${path.relative(process.cwd(), backup.rutaBackup)}`);
-          if (opciones.estado) {
-            registrarBackup(opciones.estado, {
-              rutaOriginal: destino,
-              rutaBackup: backup.rutaBackup,
-              version: opciones.versionAnterior,
-              evolucionado: true,
-            });
-          }
+
+    if (fs.existsSync(cmpDestino)) {
+      const strategy = decideUpdateStrategy(cmpDestino, cmpOrigen, opciones.versionActual || '', { manifestPath: opciones.manifestPath });
+      const hashAntes = (() => { try { return canonicalHash(fs.readFileSync(cmpDestino, 'utf8')); } catch { return null; } })();
+
+      if (strategy.strategy === 'preserve') {
+        console.log(`  ★ Evolucionado: ${nombreArchivo} — preservado (${strategy.reason})`);
+        return { instalado: false, evolucionado: true, destino };
+      }
+
+      if (strategy.strategy === 'conflict') {
+        // Población A — evolución del usuario. NUNCA overwrite: backup + merge (diff).
+        const backup = crearBackup(process.cwd(), cmpDestino, versionBackup);
+        if (!backup.respaldado) {
+          console.log(`  ⚠ Backup falló (${backup.error || 'desconocido'}) para ${nombreArchivo} — merge abortado, original preservado`);
+          auditarEscritura({ archivo: path.relative(process.cwd(), cmpDestino), clasificacion: 'A', accion: 'preserve', hashAntes, evidencia: `backup falló: ${backup.error || 'desconocido'}` });
+          return { instalado: false, evolucionado: true, destino, error: 'backup-failed' };
         }
+        const backupPath = backup.rutaBackup;
+        console.log(`  ⚠ Conflicto: ${nombreArchivo} — evolución del usuario (${strategy.reason})`);
+        console.log(`    ↩ Backup: ${path.relative(process.cwd(), backupPath)}`);
+        if (opciones.estado) {
+          registrarBackup(opciones.estado, { rutaOriginal: cmpDestino, rutaBackup: backupPath, version: versionBackup, evolucionado: true });
+        }
+        // Diff centralizado bajo el root del install (no adyacente al comando/skill).
+        const reconcileDir = path.join(rutas.base || process.cwd(), '.planning', 'evolution', 'reconcile');
+        const merge = mergeEvolved(cmpDestino, cmpOrigen, opciones.versionActual || '', { diffDir: reconcileDir });
+        if (merge.merged && merge.diffPath) {
+          console.log(`    ⊕ Diff generado: ${path.relative(process.cwd(), merge.diffPath)} (${merge.diffsCount} mutaciones)`);
+          console.log(`    → Re-aplicar con /swl:autoresearch ${nombreArchivo} sobre v${opciones.versionActual}`);
+        }
+        // Habilidad: actualizar recursos del directorio PRESERVANDO el SKILL.md
+        // evolucionado del usuario (los demás archivos sí se actualizan).
+        let recursosActualizados = false;
+        if (esDirSkill) {
+          try {
+            copiarDirectorio(origenAbsoluto, destino, { excepto: new Set(['SKILL.md']) });
+            recursosActualizados = true;
+          } catch (e) { console.log(`    ⚠ No se pudieron actualizar recursos del skill: ${e.message}`); }
+        }
+        const aud = auditarEscritura({ archivo: path.relative(process.cwd(), cmpDestino), clasificacion: 'A', accion: 'merge', hashAntes, backupPath, evidencia: strategy.reason });
+        if (!aud.registrado) console.log(`    ⚠ Auditoría no registrada: ${aud.error}`);
+        return { instalado: recursosActualizados, evolucionado: true, destino };
       }
-      // Intentar merge: generar diff de mutaciones para re-aplicación
-      const merge = mergeEvolved(destino, origenAbsoluto, opciones.versionActual || '');
-      if (merge.merged && merge.diffPath) {
-        console.log(`    ⊕ Diff generado: ${path.relative(process.cwd(), merge.diffPath)} (${merge.diffsCount} mutaciones)`);
-        console.log(`    → Ejecutar /swl:autoresearch para re-aplicar mutaciones sobre v${opciones.versionActual}`);
-      } else if (merge.merged) {
-        console.log(`    ⊕ Merge exitoso: campos evolved re-aplicados sin cambios de contenido`);
-        return { instalado: false, evolucionado: true, destino };
+
+      if (strategy.strategy === 'overwrite' && strategy.origin === 'shipped') {
+        // Población B — shipped-evolved intacto. Actualización segura con backup.
+        let hashDespues = null;
+        try { hashDespues = canonicalHash(fs.readFileSync(cmpOrigen, 'utf8')); } catch { /* best-effort */ }
+
+        if (esDirSkill) {
+          // ALTO (nemesis O6): respaldar el DIRECTORIO COMPLETO (recursos incluidos)
+          // antes de sobrescribir — el usuario pudo modificar recursos/ aunque no
+          // tocara el SKILL.md. Overwrite controlado en-bloque (no fall-through).
+          const backupDir = path.join(process.cwd(), '.planning', 'backups', `v${versionBackup}`, path.relative(process.cwd(), destino));
+          let backupOk = false;
+          try { copiarDirectorio(destino, backupDir); backupOk = true; } catch (e) { console.log(`  ⚠ Backup de directorio falló (${e.message})`); }
+          if (!backupOk) {
+            auditarEscritura({ archivo: path.relative(process.cwd(), destino), clasificacion: 'B', accion: 'preserve', hashAntes, evidencia: 'backup de directorio falló' });
+            return { instalado: false, evolucionado: true, destino, error: 'backup-failed' };
+          }
+          console.log(`  ⇪ Actualizado (shipped-evolved): ${nombreArchivo} — ${strategy.reason}`);
+          if (opciones.estado) registrarBackup(opciones.estado, { rutaOriginal: destino, rutaBackup: backupDir, version: versionBackup, evolucionado: true });
+          const aud = auditarEscritura({ archivo: path.relative(process.cwd(), cmpDestino), clasificacion: 'B', accion: 'overwrite', hashAntes, hashDespues, backupPath: backupDir, evidencia: strategy.reason });
+          if (!aud.registrado) console.log(`    ⚠ Auditoría no registrada: ${aud.error}`);
+          copiarDirectorio(origenAbsoluto, destino); // overwrite dir completo (recursos + SKILL.md)
+          return { instalado: true, evolucionado: true, destino };
+        }
+
+        // Componente-archivo (agentes/comandos/reglas): backup del archivo + fall-through.
+        const backup = crearBackup(process.cwd(), cmpDestino, versionBackup);
+        // H1 (nemesis O5): si el backup falla, NO sobrescribir — preservar original.
+        if (!backup.respaldado) {
+          console.log(`  ⚠ Backup falló (${backup.error || 'desconocido'}) para ${nombreArchivo} — overwrite abortado, original preservado`);
+          auditarEscritura({ archivo: path.relative(process.cwd(), cmpDestino), clasificacion: 'B', accion: 'preserve', hashAntes, evidencia: `backup falló: ${backup.error || 'desconocido'}` });
+          return { instalado: false, evolucionado: true, destino, error: 'backup-failed' };
+        }
+        const backupPath = backup.rutaBackup;
+        console.log(`  ⇪ Actualizado (shipped-evolved): ${nombreArchivo} — ${strategy.reason}`);
+        if (opciones.estado) {
+          registrarBackup(opciones.estado, { rutaOriginal: cmpDestino, rutaBackup: backupPath, version: versionBackup, evolucionado: true });
+        }
+        const aud = auditarEscritura({ archivo: path.relative(process.cwd(), cmpDestino), clasificacion: 'B', accion: 'overwrite', hashAntes, hashDespues, backupPath, evidencia: strategy.reason });
+        if (!aud.registrado) console.log(`    ⚠ Auditoría no registrada: ${aud.error}`);
+        forzarEscrituraEvolved = true; // bypassa la verificación de colisión sin --force
       }
+      // strategy === 'overwrite' sin origin shipped = destino no evolucionado →
+      // sigue al flujo normal de colisión/force más abajo.
     }
   }
 
   // Verificar colisión
-  if (fs.existsSync(destino) && !opciones.force) {
+  if (fs.existsSync(destino) && !opciones.force && !forzarEscrituraEvolved) {
     if (typeof opciones.onProgress === 'function') {
       opciones.onProgress({
         tipo: 'colision',
@@ -1219,8 +1283,9 @@ function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
     return { instalado: false, colision: true };
   }
 
-  // Nivel 2: Backup antes de sobreescribir con --force
-  if (fs.existsSync(destino) && opciones.force && opciones.versionAnterior) {
+  // Nivel 2: Backup antes de sobreescribir con --force (el caso B shipped-evolved
+  // ya hizo su propio backup arriba; no duplicar).
+  if (fs.existsSync(destino) && opciones.force && opciones.versionAnterior && !forzarEscrituraEvolved) {
     const backup = crearBackup(process.cwd(), destino, opciones.versionAnterior);
     if (backup.respaldado) {
       if (typeof opciones.onProgress === 'function') {
@@ -1305,18 +1370,24 @@ function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
 /**
  * Copia un directorio recursivamente
  */
-function copiarDirectorio(origen, destino) {
+function copiarDirectorio(origen, destino, opts = {}) {
   if (!fs.existsSync(destino)) {
     fs.mkdirSync(destino, { recursive: true });
   }
 
+  // `excepto` (Fase 16): nombres de archivo del nivel superior a NO copiar.
+  // Se usa para preservar el SKILL.md evolucionado del usuario (población A)
+  // mientras se actualizan los demás recursos del directorio del skill.
+  const excepto = opts.excepto instanceof Set ? opts.excepto : null;
+
   const entradas = fs.readdirSync(origen, { withFileTypes: true });
   for (const entrada of entradas) {
+    if (excepto && excepto.has(entrada.name)) continue;
     const src = path.join(origen, entrada.name);
     const dst = path.join(destino, entrada.name);
 
     if (entrada.isDirectory()) {
-      copiarDirectorio(src, dst);
+      copiarDirectorio(src, dst); // exclusión solo aplica al nivel superior
     } else {
       fs.copyFileSync(src, dst);
     }
@@ -1371,3 +1442,5 @@ function limpiarReglasSinStack(dirReglas, stackDetectado) {
 }
 
 module.exports = install;
+// Export para tests del wiring de evolución (Fase 16 T-19).
+module.exports.instalarArchivo = instalarArchivo;

package/scripts/lib/audit-evolved.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * audit-evolved — Registro append-only de escrituras del instalador sobre
+ * componentes evolucionados (Fase 16, REQ-16-08).
+ *
+ * Toda operación que escriba sobre un componente `evolved` (overwrite de un
+ * shipped-evolved B, o merge de una evolución del usuario A) debe dejar rastro
+ * en `.planning/AUDITORIA.md` con: archivo, clasificación A/B, acción, hashes
+ * antes/después y ruta del backup. Cumple `reglas/gobernanza.md § Auditoría`
+ * (append-only) y `reglas/seguridad-agentes.md § no-degradación-silenciosa`.
+ *
+ * Zero-deps. AUDITORIA.md es append-only → fs.appendFileSync (no atomicWrite,
+ * que reescribiría todo el archivo).
+ *
+ * @module scripts/lib/audit-evolved
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const HEADER = '# AUDITORIA\n\n' +
+  'Registro append-only de operaciones de alto riesgo (no borrar entradas).\n';
+
+/**
+ * Appenda una entrada de auditoría por escritura sobre un componente evolved.
+ *
+ * @param {object} e
+ * @param {string} e.archivo        - Ruta (relativa) del componente afectado.
+ * @param {'A'|'B'} e.clasificacion - A = evolución del usuario (merge); B = shipped (overwrite).
+ * @param {string} e.accion         - 'overwrite' | 'merge' | 'preserve'.
+ * @param {string} [e.hashAntes]    - Hash canónico previo.
+ * @param {string} [e.hashDespues]  - Hash canónico posterior.
+ * @param {string} [e.backupPath]   - Ruta del backup creado antes de escribir.
+ * @param {string} [e.evidencia]    - Razón/criterio que clasificó A vs B.
+ * @param {string} [e.timestamp]    - ISO; default `new Date().toISOString()`.
+ * @param {string} [e.cwd]          - Raíz del proyecto; default process.cwd().
+ * @returns {{ registrado: boolean, ruta: string }}
+ */
+function auditarEscritura(e) {
+  const cwd = e.cwd || process.cwd();
+  const ruta = path.join(cwd, '.planning', 'AUDITORIA.md');
+  try {
+    fs.mkdirSync(path.dirname(ruta), { recursive: true });
+    if (!fs.existsSync(ruta)) fs.writeFileSync(ruta, HEADER, 'utf8');
+
+    const ts = e.timestamp || new Date().toISOString();
+    const corto = (h) => (h ? String(h).slice(0, 12) : 'n/a');
+    const lineas = [
+      '',
+      `## [${ts}] evolved-${e.accion}`,
+      '',
+      `**Agente**: instalador`,
+      `**Archivo**: ${e.archivo}`,
+      `**Clasificación**: ${e.clasificacion === 'A' ? 'A (evolución del usuario — merge)' : 'B (shipped-evolved — overwrite)'}`,
+      `**Acción**: ${e.accion}`,
+      `**Hash antes**: ${corto(e.hashAntes)}`,
+      `**Hash después**: ${corto(e.hashDespues)}`,
+      `**Backup**: ${e.backupPath ? path.relative(cwd, e.backupPath).replace(/\\/g, '/') : 'n/a'}`,
+      `**Evidencia**: ${e.evidencia || 'n/a'}`,
+      '',
+    ];
+    fs.appendFileSync(ruta, lineas.join('\n'), 'utf8');
+    return { registrado: true, ruta };
+  } catch (err) {
+    // No-fallback-silencioso: el caller debe ver el fallo de auditoría.
+    return { registrado: false, ruta, error: err.message };
+  }
+}
+
+module.exports = { auditarEscritura };

package/scripts/lib/canonical-hash.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * canonical-hash — Hash determinista del "cuerpo canónico" de un componente SWL.
+ *
+ * El discriminador A/B de la Fase 16 necesita distinguir:
+ *   - Población A: evolución genuina del usuario (cuerpo modificado tras recibir
+ *     el componente del paquete) → debe MERGE, jamás overwrite.
+ *   - Población B: shipped-evolved de fábrica (frontmatter `evolved:*` espurio
+ *     puesto por el repo madre, cuerpo idéntico al canónico) → actualizable.
+ *
+ * La señal es el cuerpo SIN los campos `evolved-*`: si el cuerpo instalado
+ * hashea igual al cuerpo canónico de la versión `evolved-from`, el usuario NO
+ * lo tocó (es B). Si difiere, hubo mutación real del usuario (es A).
+ *
+ * El hash ignora los campos `evolved-*` del frontmatter (que el shipping mete y
+ * quita) y normaliza CRLF→LF para ser estable cross-OS (el usuario corre
+ * Windows; el CI/manifiesto se genera en cualquier plataforma).
+ *
+ * Zero-deps: solo `crypto` nativo. Patrón de hashing precedente en
+ * `hooks/lib/merkle-audit.js` y `scripts/lib/plan-lock.js`.
+ *
+ * @module scripts/lib/canonical-hash
+ */
+
+const { createHash } = require('crypto');
+
+/**
+ * Normaliza el contenido a su "cuerpo canónico":
+ *   - Elimina toda línea de frontmatter `evolved*:` (`evolved:`, `evolved-from:`,
+ *     `evolved-at:`, `evolved-by:`, `evolved-rounds:`, `evolved-score:`,
+ *     `evolved-note:`, `evolved-origin:`).
+ *   - Normaliza line endings CRLF/CR → LF.
+ *   - Recorta whitespace final (un solo `\n` al cierre) para que diferencias de
+ *     EOF no cambien el hash.
+ *
+ * El filtro `^evolved[-\w]*:` se aplica EXCLUSIVAMENTE al bloque frontmatter.
+ * Aplicarlo a todo el archivo (bug detectado en auditoría nemesis Fase 16)
+ * borraría líneas legítimas del body que empiecen con `evolved-*` (p. ej.
+ * `aprender.md`/`evolucionar.md` documentan esos campos en su cuerpo), lo que
+ * causaba un FALSO POSITIVO en el discriminador A/B: el cuerpo del usuario
+ * hasheaba igual al baseline → se clasificaba como shipped → overwrite de
+ * evolución del usuario (violación del invariante merge-no-overwrite).
+ *
+ * Normaliza CRLF/CR → LF (estable cross-OS) antes de hashear.
+ *
+ * @param {string} content
+ * @returns {string} cuerpo canónico normalizado
+ */
+function canonicalBody(content) {
+  const norm = String(content).replace(/\r\n|\r/g, '\n');
+  // Separar frontmatter (entre los primeros dos `---`) del body.
+  const m = norm.match(/^(---\n[\s\S]*?\n---\n?)([\s\S]*)$/);
+  if (!m) {
+    // Sin frontmatter: el contenido completo es body, no se filtra nada.
+    return norm.replace(/\s+$/, '') + '\n';
+  }
+  const fmFiltrado = m[1]
+    .split('\n')
+    .filter((line) => !/^evolved[-\w]*:/i.test(line)) // flag i: simétrico con la detección
+    .join('\n');
+  return (fmFiltrado + m[2]).replace(/\s+$/, '') + '\n';
+}
+
+/**
+ * SHA256 hex (64 chars) del cuerpo canónico de un componente.
+ *
+ * @param {string} content - Contenido completo del archivo `.md`.
+ * @returns {string} hash hex de 64 caracteres
+ */
+function canonicalHash(content) {
+  return createHash('sha256').update(canonicalBody(content), 'utf8').digest('hex');
+}
+
+/**
+ * Decide si el contenido local corresponde al cuerpo canónico shipped de una
+ * versión dada (= NO fue tocado por el usuario = población B).
+ *
+ * @param {object} manifiesto    - `{ version: { rutaRel: sha256 } }`
+ * @param {string} versionPrev   - Versión base (típicamente `evolved-from`).
+ * @param {string} rutaRel       - Ruta relativa del componente (ej. `agentes/X-swl.md`).
+ * @param {string} contenidoLocal- Contenido completo del archivo instalado.
+ * @returns {boolean} true si el hash local coincide con el baseline de esa versión.
+ */
+function hashCoincide(manifiesto, versionPrev, rutaRel, contenidoLocal) {
+  if (!manifiesto || typeof manifiesto !== 'object') return false;
+  const porVersion = manifiesto[versionPrev];
+  if (!porVersion || typeof porVersion !== 'object') return false;
+  const esperado = porVersion[rutaRel];
+  if (!esperado) return false;
+  return canonicalHash(contenidoLocal) === esperado;
+}
+
+module.exports = { canonicalBody, canonicalHash, hashCoincide };

package/scripts/lib/evolved-fuente.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * evolved-fuente — Higiene de marcadores de evolución en el repo madre (Fase 16).
+ *
+ * Invariante del sistema: `evolved: true` (frontmatter o sidecar `.evolved.json`)
+ * significa "este componente fue modificado por un USUARIO tras recibirlo del
+ * paquete". En el repo madre (fuente) NO debe existir ningún marcador evolved —
+ * los cambios del mantenedor se rastrean por git + bump de `version`. Un marcador
+ * evolved en el fuente es "shipped-evolved" espurio: confunde al discriminador
+ * A/B del instalador y congela el componente en las máquinas de los usuarios.
+ *
+ * Esta lib:
+ *   - `listarOfensores(raiz)`: detecta marcadores evolved en el fuente (gate inverso).
+ *   - `limpiar(raiz, opts)`: elimina los marcadores (frontmatter evolved-* y
+ *     sidecars), preservando el body intacto.
+ *
+ * Dominios cubiertos: agentes/, habilidades/, comandos/, reglas/.
+ * Zero-deps. CRLF-safe.
+ *
+ * @module scripts/lib/evolved-fuente
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require('../../hooks/lib/atomic-write'));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+}
+
+const DOMINIOS = ['agentes', 'habilidades', 'comandos', 'reglas'];
+
+function _walk(dir, pred, out) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) _walk(p, pred, out);
+    else if (pred(entry.name)) out.push(p);
+  }
+}
+
+function _rel(raiz, abs) {
+  return path.relative(raiz, abs).replace(/\\/g, '/');
+}
+
+/** ¿El frontmatter (primer bloque ---) declara evolved: true|yes? */
+function _frontmatterTieneEvolved(content) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!m) return false;
+  return /^evolved:\s*(true|yes)\b/mi.test(m[1]);
+}
+
+/**
+ * Lista los marcadores evolved presentes en el fuente.
+ * @param {string} [raiz=process.cwd()]
+ * @returns {{ frontmatter: string[], sidecars: string[] }}
+ */
+function listarOfensores(raiz) {
+  raiz = raiz || process.cwd();
+  const frontmatter = [];
+  const sidecars = [];
+
+  for (const d of DOMINIOS) {
+    const base = path.join(raiz, d);
+
+    const mds = [];
+    _walk(base, (name) => name.endsWith('.md'), mds);
+    for (const abs of mds) {
+      try {
+        if (_frontmatterTieneEvolved(fs.readFileSync(abs, 'utf8'))) frontmatter.push(_rel(raiz, abs));
+      } catch { /* ilegible: lo ignora el gate, lo verá el linter de IO */ }
+    }
+
+    const sc = [];
+    _walk(base, (name) => name === '.evolved.json', sc);
+    for (const abs of sc) sidecars.push(_rel(raiz, abs));
+  }
+
+  return {
+    frontmatter: frontmatter.sort(),
+    sidecars: sidecars.sort(),
+  };
+}
+
+/**
+ * Elimina las líneas `evolved-*` SOLO del bloque frontmatter, preservando el
+ * body (que puede tener líneas `evolved-*` legítimas como documentación, p. ej.
+ * aprender.md / evolucionar.md).
+ * @param {string} content
+ * @returns {string}
+ */
+function limpiarFrontmatter(content) {
+  const m = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
+  if (!m) return content;
+  const eol = m[1].includes('\r\n') ? '\r\n' : '\n';
+  const fmLimpio = m[2]
+    .split(/\r?\n/)
+    // flag `i`: simétrico con la detección case-insensitive de
+    // _frontmatterTieneEvolved. Sin él, `Evolved: true` se detectaría como
+    // ofensor pero no se limpiaría → --fix inútil (nemesis O4).
+    .filter((line) => !/^evolved[-\w]*:/i.test(line))
+    .join(eol);
+  return m[1] + fmLimpio + m[3] + content.slice(m[0].length);
+}
+
+/**
+ * Limpia todos los marcadores evolved del fuente.
+ * @param {string} [raiz=process.cwd()]
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {Array<{ tipo: string, archivo: string }>} acciones realizadas/propuestas
+ */
+function limpiar(raiz, { dryRun = false } = {}) {
+  raiz = raiz || process.cwd();
+  const { frontmatter, sidecars } = listarOfensores(raiz);
+  const acciones = [];
+
+  for (const rel of frontmatter) {
+    const abs = path.join(raiz, rel);
+    const orig = fs.readFileSync(abs, 'utf8');
+    const limpio = limpiarFrontmatter(orig);
+    if (limpio !== orig) {
+      acciones.push({ tipo: 'strip-frontmatter', archivo: rel });
+      if (!dryRun) atomicWriteSync(abs, limpio, 'utf8');
+    }
+  }
+
+  for (const rel of sidecars) {
+    acciones.push({ tipo: 'rm-sidecar', archivo: rel });
+    if (!dryRun) fs.unlinkSync(path.join(raiz, rel));
+  }
+
+  return acciones;
+}
+
+module.exports = { listarOfensores, limpiar, limpiarFrontmatter, DOMINIOS };