@saulwade/swl-ses 2.1.0 → 2.2.1

package/scripts/cli/verificar-plan.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Subcomando `swl-ses verificar-plan --fase=N` — verificación read-only del lock
+ * de un PLAN (gate G1). Lo usa /swl:ejecutar-fase antes de implementar y
+ * /swl:aprobar-plan Paso 2 para detectar planes ya firmados/mutados/legacy.
+ *
+ * Reemplaza el `node -e "require('./scripts/lib/plan-lock')"` inline que se
+ * rompía downstream (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Exit 0 si ok (firmado o legacy); exit 1 si mutado/sin-firmar/corrupto.
+ *
+ * Uso: swl-ses verificar-plan --fase=N [--plan=<ruta>]
+ */
+
+const { verificarPlan } = require('../lib/plan-lock');
+const { resolverPlanPath } = require('../lib/resolver-plan-fase');
+
+function verificarPlanCli(opciones = {}) {
+  opciones = opciones || {};
+  const planPath = resolverPlanPath(opciones);
+  if (!planPath) {
+    console.error('Uso: swl-ses verificar-plan --fase=N [--plan=<ruta>]');
+    process.exit(1);
+  }
+  const r = verificarPlan(planPath);
+  console.log(JSON.stringify(r, null, 2));
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = verificarPlanCli;
+
+if (require.main === module) {
+  const { parsearOpciones } = require('../lib/parsear-opciones');
+  verificarPlanCli(parsearOpciones(process.argv.slice(2)));
+}

package/scripts/cli/verificar-trazabilidad.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Wrapper CLI para el subcomando `swl-ses verificar-trazabilidad`.
+ *
+ * Traduce las opciones parseadas del bin a las flags que espera el script
+ * standalone `scripts/verificar-trazabilidad.js` (que lee process.argv y hace
+ * su propio process.exit). Mismo patrón que scripts/cli/audit-claudemd.js.
+ *
+ * Reemplaza el `node scripts/verificar-trazabilidad.js` relativo al proyecto que
+ * /swl:aprobar-plan invocaba — roto downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses verificar-trazabilidad --fase=N [--solo-plan] [--json]
+ */
+
+const { main } = require('../verificar-trazabilidad.js');
+
+function verificarTrazabilidad(opciones = {}) {
+  opciones = opciones || {};
+  const args = [];
+  if (opciones.fase != null && opciones.fase !== true) args.push(`--fase=${opciones.fase}`);
+  if (opciones['solo-plan'] || opciones.solo_plan) args.push('--solo-plan');
+  if (opciones.json) args.push('--json');
+
+  const argvOriginal = process.argv;
+  process.argv = ['node', 'verificar-trazabilidad.js', ...args];
+  try {
+    main();
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = verificarTrazabilidad;

package/scripts/derivar-feature-list.js

@@ -486,4 +486,5 @@ module.exports = {
   enriquecerDesdeFases,
   generarFeatureList,
   normalizarEstado,
+  main,
 };

package/scripts/generar-canonical-hashes.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * generar-canonical-hashes — Genera/actualiza `manifiestos/canonical-hashes.json`.
+ *
+ * Recorre los componentes versionables del fuente (agentes, skills, comandos,
+ * reglas) y registra el hash del cuerpo canónico (sin campos `evolved-*`,
+ * CRLF→LF) bajo la versión actual del paquete:
+ *
+ *   { "<version>": { "<rutaRel>": "<sha256>", ... }, ... }
+ *
+ * El manifiesto es la baseline que el discriminador A/B (Fase 16) usa para
+ * decidir si una copia instalada `evolved:true` fue tocada por el usuario
+ * (población A → merge) o es shipped-evolved intacto (población B → actualizar).
+ *
+ * Modelo de amenaza (auditoría nemesis Fase 16, hallazgo BAJO): el manifiesto
+ * NO lleva firma criptográfica propia. No es un gap incremental: viaja DENTRO
+ * del paquete npm publicado, el mismo límite de confianza que `evolution-tracker.js`
+ * y todo el código. Quien pueda alterar este JSON ya puede alterar el código que
+ * lo consume — firmar el manifiesto sin firmar el paquete entero no añade defensa.
+ * La integridad la provee la cadena de publicación de npm (provenance/SBOM del
+ * release). NO se añade firma propia (sería seguridad teatral). Reabrir SOLO si
+ * el manifiesto se expone como archivo editable fuera del paquete (p. ej. P2P).
+ *
+ * Idempotente: dos corridas sin cambios producen el mismo archivo (keys
+ * ordenadas). Preserva entradas de versiones anteriores (histórico necesario
+ * para discriminar contra clientes que evolucionaron desde una versión vieja).
+ *
+ * Uso:  node scripts/generar-canonical-hashes.js [--check]
+ *   --check  No escribe; exit 2 si el manifiesto está desactualizado (uso CI).
+ *
+ * @module scripts/generar-canonical-hashes
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { canonicalHash } = require('./lib/canonical-hash');
+
+const RAIZ = path.resolve(__dirname, '..');
+const MANIFIESTO = path.join(RAIZ, 'manifiestos', 'canonical-hashes.json');
+
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require('../hooks/lib/atomic-write'));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+}
+
+/** Recolecta los componentes versionables como rutas relativas a la raíz. */
+function recolectarComponentes() {
+  const rutas = [];
+
+  const listarMd = (dirRel) => {
+    const dir = path.join(RAIZ, dirRel);
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      if (entry.endsWith('.md')) rutas.push(path.posix.join(dirRel, entry));
+    }
+  };
+
+  // Agentes, comandos, reglas: archivos .md planos.
+  listarMd('agentes');
+  listarMd('comandos/swl');
+  listarMd('reglas');
+
+  // Habilidades: cada skill es un directorio con SKILL.md.
+  const habDir = path.join(RAIZ, 'habilidades');
+  if (fs.existsSync(habDir)) {
+    for (const entry of fs.readdirSync(habDir)) {
+      const skillMd = path.join(habDir, entry, 'SKILL.md');
+      if (fs.existsSync(skillMd)) rutas.push(path.posix.join('habilidades', entry, 'SKILL.md'));
+    }
+  }
+
+  return rutas.sort();
+}
+
+/** Construye el mapa { rutaRel: hash } de la versión actual del fuente. */
+function hashesActuales() {
+  const out = {};
+  for (const rel of recolectarComponentes()) {
+    const abs = path.join(RAIZ, rel);
+    out[rel] = canonicalHash(fs.readFileSync(abs, 'utf8'));
+  }
+  return out;
+}
+
+/** Ordena recursivamente las keys de un objeto plano de 2 niveles. */
+function ordenar(manifiesto) {
+  const out = {};
+  for (const version of Object.keys(manifiesto).sort()) {
+    const porVersion = manifiesto[version];
+    out[version] = {};
+    for (const k of Object.keys(porVersion).sort()) out[version][k] = porVersion[k];
+  }
+  return out;
+}
+
+function cargarManifiesto() {
+  if (!fs.existsSync(MANIFIESTO)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(MANIFIESTO, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function generar({ check = false } = {}) {
+  const version = require(path.join(RAIZ, 'package.json')).version;
+  const manifiesto = cargarManifiesto();
+  manifiesto[version] = hashesActuales();
+  const ordenado = ordenar(manifiesto);
+  const serializado = JSON.stringify(ordenado, null, 2) + '\n';
+
+  const previo = fs.existsSync(MANIFIESTO) ? fs.readFileSync(MANIFIESTO, 'utf8') : '';
+  // Comparación EOL-tolerante: git puede normalizar el .json a CRLF en checkout
+  // (Windows). El contenido semántico es idéntico; comparar normalizado evita
+  // un falso "desactualizado" en el gate `--check` cross-OS.
+  const norm = (s) => s.replace(/\r\n/g, '\n');
+  const cambio = norm(previo) !== norm(serializado);
+
+  if (check) {
+    if (cambio) {
+      console.error(`[canonical-hashes] DESACTUALIZADO para v${version} — ejecuta: node scripts/generar-canonical-hashes.js`);
+      process.exitCode = 2;
+    } else {
+      console.log(`[canonical-hashes] OK — v${version} al día (${Object.keys(ordenado[version]).length} componentes)`);
+    }
+    return ordenado;
+  }
+
+  if (cambio) {
+    atomicWriteSync(MANIFIESTO, serializado, 'utf8');
+    console.log(`[canonical-hashes] escrito v${version} (${Object.keys(ordenado[version]).length} componentes) → ${path.relative(RAIZ, MANIFIESTO)}`);
+  } else {
+    console.log(`[canonical-hashes] sin cambios para v${version}`);
+  }
+  return ordenado;
+}
+
+if (require.main === module) {
+  generar({ check: process.argv.includes('--check') });
+}
+
+module.exports = { generar, hashesActuales, recolectarComponentes, MANIFIESTO };

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/auditar-invocaciones-comandos.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * auditar-invocaciones-comandos.js
+ *
+ * Gate anti-regresión de la clase de bug "invocación relativa al proyecto en
+ * comandos user-facing" (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Un comando que corre en el proyecto del usuario NUNCA debe invocar scripts SWL
+ * con ruta relativa al proyecto (`node scripts/lib/...`, `node hooks/...`,
+ * `require('./scripts/...')`): esas rutas no existen downstream. Debe usar el
+ * subcomando del CLI (`swl-ses <sub>` / `npx ... <sub>` / `node scripts/cli/<sub>.js`).
+ *
+ * Solo escanea bloques de código (``` ... ```) para no marcar menciones
+ * prohibitivas en prosa. Excluye `scripts/cli/` (forma repo-madre sancionada).
+ *
+ * Función pura + entrypoint CLI con exit 1 si hay violaciones.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Comandos que corren SOLO en el repo madre de swl-ses (el CWD ES el repo, así
+// que `node scripts/...` relativo es correcto). NO son user-facing.
+const SELF_DEV = new Set([
+  'release',
+  'contribuir',
+  'evaluar-skill',
+  'reflect-skills',
+]);
+
+// Patrones de invocación relativa al proyecto que se rompen downstream.
+// Se evalúan SOLO dentro de bloques de código.
+const PATRONES = [
+  { re: /\bnode\s+(?:\.\/)?scripts\/(?!cli\/)/, desc: 'node scripts/ (usa swl-ses <sub>)' },
+  { re: /\bnode\s+(?:\.\/)?hooks\//, desc: 'node hooks/ (usa swl-ses <sub>)' },
+  { re: /require\(\s*['"]\.\.?\/scripts\//, desc: "require('./scripts/ inline" },
+  { re: /require\(\s*['"]\.\.?\/hooks\//, desc: "require('./hooks/ inline" },
+];
+
+/**
+ * @param {string} [comandosDir] default: comandos/swl relativo al repo de este script.
+ * @returns {{ok:boolean, violaciones:Array<{comando:string,linea:number,texto:string,patron:string}>, escaneados:number}}
+ */
+function auditarInvocacionesComandos(comandosDir) {
+  const dir = comandosDir || path.join(__dirname, '..', '..', 'comandos', 'swl');
+  const violaciones = [];
+  let escaneados = 0;
+
+  let archivos;
+  try {
+    archivos = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
+  } catch {
+    return { ok: true, violaciones, escaneados: 0 };
+  }
+
+  for (const archivo of archivos) {
+    const comando = archivo.replace(/\.md$/, '');
+    if (SELF_DEV.has(comando)) continue;
+    escaneados++;
+
+    const contenido = fs.readFileSync(path.join(dir, archivo), 'utf8');
+    const lineas = contenido.split('\n');
+    let dentroCodigo = false;
+
+    for (let i = 0; i < lineas.length; i++) {
+      const linea = lineas[i];
+      if (/^\s*```/.test(linea)) {
+        dentroCodigo = !dentroCodigo;
+        continue;
+      }
+      if (!dentroCodigo) continue;
+      for (const { re, desc } of PATRONES) {
+        if (re.test(linea)) {
+          violaciones.push({
+            comando,
+            linea: i + 1,
+            texto: linea.trim(),
+            patron: desc,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { ok: violaciones.length === 0, violaciones, escaneados };
+}
+
+module.exports = { auditarInvocacionesComandos, SELF_DEV };
+
+if (require.main === module) {
+  const r = auditarInvocacionesComandos();
+  if (r.ok) {
+    console.log(`[OK] invocaciones-comandos — ${r.escaneados} comandos user-facing sin rutas relativas al proyecto`);
+    process.exit(0);
+  }
+  console.error(`[FALLA] invocaciones-comandos — ${r.violaciones.length} invocación(es) relativa(s) al proyecto en comandos user-facing:`);
+  for (const v of r.violaciones) {
+    console.error(`  ${v.comando}.md:${v.linea} [${v.patron}] ${v.texto}`);
+  }
+  console.error('\nUsa el patrón cross-scope (docs/invocacion-cli-cross-scope.md): swl-ses <sub> / npx ... <sub> / node scripts/cli/<sub>.js');
+  process.exit(1);
+}