@saulwade/swl-ses 1.4.2 → 1.5.0

package/scripts/derivar-feature-list.js

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * derivar-feature-list.js — Sub-fase 5 (Opción B desde análisis cc-sdd)
+ *
+ * Genera `.planning/feature-list.json` como **state machine machine-readable**
+ * derivado del Markdown libre de `.planning/HOJA-RUTA.md` y los PLAN.md/
+ * RESUMEN.md de cada fase en `.planning/fases/`.
+ *
+ * El HOJA-RUTA.md es la fuente de verdad human-friendly; este script produce
+ * una proyección JSON consumible por:
+ *   - `/swl:dashboard` (vista de progreso de fases)
+ *   - `/swl:metricas` (cálculo de velocity, lead time, completitud)
+ *   - Hooks de observabilidad
+ *   - Auditoría externa programática
+ *
+ * NO reemplaza HOJA-RUTA.md. Si entran en conflicto, HOJA-RUTA.md gana —
+ * este JSON es una derivación cache, regenerable.
+ *
+ * Inspirado en `feature_list.json` de harness-sdd-main, adaptado al modelo
+ * por-fase de swl-ses (no por-feature).
+ *
+ * Uso:
+ *   node scripts/derivar-feature-list.js
+ *   node scripts/derivar-feature-list.js --out custom/path.json
+ *   node scripts/derivar-feature-list.js --check       # exit 1 si JSON está stale
+ *   node scripts/derivar-feature-list.js --verbose
+ *
+ * Exit codes:
+ *   0  OK / generado / sincronizado
+ *   1  HOJA-RUTA.md ausente o .planning/ no inicializado
+ *   2  --check detectó drift entre HOJA-RUTA.md y feature-list.json
+ *   3  Error de parsing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CWD = process.cwd();
+const PLANNING_DIR = path.join(CWD, '.planning');
+const HOJA_RUTA = path.join(PLANNING_DIR, 'HOJA-RUTA.md');
+const FASES_DIR = path.join(PLANNING_DIR, 'fases');
+const DEFAULT_OUT = path.join(PLANNING_DIR, 'feature-list.json');
+
+const ESTADOS_VALIDOS = new Set([
+  'pendiente',
+  'en_progreso',
+  'spec_listo',
+  'completado',
+  'bloqueado',
+]);
+
+// ─── Parsing del HOJA-RUTA.md ────────────────────────────────────────────────
+
+/**
+ * Extrae fases del HOJA-RUTA.md.
+ *
+ * Reconoce dos formatos:
+ *
+ *  1. Tabla resumen al inicio:
+ *     | Fase | Nombre | Objetivo | Duración estimada | Estado |
+ *     | 1 | Bootstrap | ... | 2 semanas | Completado |
+ *
+ *  2. Secciones detalladas:
+ *     ## Fase N: Nombre
+ *     **Objetivo**: ...
+ *     **Estado**: Pendiente | En progreso | Completado
+ *     **Fecha inicio**: YYYY-MM-DD
+ *     **Fecha fin real**: YYYY-MM-DD
+ *
+ * Si solo existe la tabla, se usa esa. Si existen ambos, las secciones
+ * detalladas ganan (más metadata).
+ */
+function parsearHojaRuta(contenido) {
+  const fases = new Map(); // numero → fase
+
+  // Parsear tabla resumen
+  parsearTablaResumen(contenido, fases);
+
+  // Parsear secciones detalladas (sobreescriben con más detalle)
+  parsearSecciones(contenido, fases);
+
+  return Array.from(fases.values()).sort((a, b) => a.numero - b.numero);
+}
+
+function parsearTablaResumen(contenido, fases) {
+  // Detecta tabla cuyo encabezado contiene "Fase" o "Phase" + "Nombre" + "Estado"
+  const lineas = contenido.split('\n');
+  let enTabla = false;
+  let idxFase = -1;
+  let idxNombre = -1;
+  let idxObjetivo = -1;
+  let idxEstado = -1;
+
+  for (const linea of lineas) {
+    const trim = linea.trim();
+    if (!trim.startsWith('|')) {
+      if (enTabla && trim === '') enTabla = false;
+      continue;
+    }
+
+    const celdas = trim.split('|').map(c => c.trim()).filter(c => c !== '');
+
+    // Detectar header
+    if (idxFase === -1) {
+      const lowered = celdas.map(c => c.toLowerCase());
+      const fa = lowered.findIndex(c => c === 'fase' || c === 'phase' || c === '#');
+      const no = lowered.findIndex(c => c === 'nombre' || c === 'name');
+      const ob = lowered.findIndex(c => c === 'objetivo' || c === 'objective');
+      const es = lowered.findIndex(c => c === 'estado' || c === 'status');
+      if (fa !== -1 && no !== -1 && es !== -1) {
+        idxFase = fa;
+        idxNombre = no;
+        idxObjetivo = ob;
+        idxEstado = es;
+        enTabla = true;
+      }
+      continue;
+    }
+
+    // Línea separadora (|---|---|)
+    if (celdas.every(c => /^-+$/.test(c.replace(/:/g, '')))) continue;
+
+    if (!enTabla) continue;
+
+    const numStr = celdas[idxFase];
+    const numero = parseInt(numStr, 10);
+    if (!Number.isFinite(numero)) continue;
+
+    fases.set(numero, {
+      numero,
+      nombre: celdas[idxNombre] || `Fase ${numero}`,
+      objetivo: idxObjetivo !== -1 ? (celdas[idxObjetivo] || null) : null,
+      estado: normalizarEstado(celdas[idxEstado]),
+      estado_raw: celdas[idxEstado],
+      fecha_inicio: null,
+      fecha_fin_estimada: null,
+      fecha_fin_real: null,
+      entregables: [],
+      criterios_verificacion: [],
+      fuente: 'tabla-resumen',
+    });
+  }
+}
+
+function parsearSecciones(contenido, fases) {
+  // ## Fase N: Nombre  o  ## Fase N — Nombre
+  const reFase = /^##\s+Fase\s+(\d+)\s*[:\-—–]\s*(.+?)$/gm;
+  const matches = [...contenido.matchAll(reFase)];
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const numero = parseInt(m[1], 10);
+    const nombre = m[2].trim();
+    const inicio = m.index + m[0].length;
+    const fin = i + 1 < matches.length ? matches[i + 1].index : contenido.length;
+    const seccion = contenido.slice(inicio, fin);
+
+    const existente = fases.get(numero) || {
+      numero,
+      nombre,
+      objetivo: null,
+      estado: 'pendiente',
+      estado_raw: 'Pendiente',
+      fecha_inicio: null,
+      fecha_fin_estimada: null,
+      fecha_fin_real: null,
+      entregables: [],
+      criterios_verificacion: [],
+      fuente: 'seccion-detallada',
+    };
+
+    existente.nombre = nombre || existente.nombre;
+    existente.fuente = 'seccion-detallada';
+
+    const objetivo = extraerCampo(seccion, 'Objetivo');
+    if (objetivo) existente.objetivo = objetivo;
+
+    const estadoRaw = extraerCampo(seccion, 'Estado');
+    if (estadoRaw) {
+      existente.estado = normalizarEstado(estadoRaw);
+      existente.estado_raw = estadoRaw;
+    }
+
+    const fIni = extraerCampo(seccion, 'Fecha inicio');
+    if (fIni && esFecha(fIni)) existente.fecha_inicio = fIni;
+
+    const fFinEst = extraerCampo(seccion, 'Fecha fin estimada');
+    if (fFinEst && esFecha(fFinEst)) existente.fecha_fin_estimada = fFinEst;
+
+    const fFinReal = extraerCampo(seccion, 'Fecha fin real');
+    if (fFinReal && esFecha(fFinReal)) existente.fecha_fin_real = fFinReal;
+
+    // Entregables (subtabla)
+    existente.entregables = parsearTablaEntregables(seccion);
+
+    // Criterios de verificación (checklist)
+    existente.criterios_verificacion = parsearChecklistCriterios(seccion);
+
+    fases.set(numero, existente);
+  }
+}
+
+function extraerCampo(seccion, etiqueta) {
+  const re = new RegExp(`^\\s*[\\*\\-]?\\s*\\*\\*${etiqueta}\\*\\*\\s*:\\s*(.+?)$`, 'mi');
+  const m = seccion.match(re);
+  if (!m) return null;
+  const valor = m[1].trim();
+  if (valor === '—' || valor === '-' || valor === '' || valor.toLowerCase().startsWith('[')) {
+    return null;
+  }
+  return valor;
+}
+
+function parsearTablaEntregables(seccion) {
+  const lineas = seccion.split('\n');
+  const entregables = [];
+  let enTabla = false;
+  let idxNum = -1, idxNombre = -1, idxDesc = -1, idxReqs = -1, idxEstado = -1;
+
+  for (const linea of lineas) {
+    const trim = linea.trim();
+    if (!trim.startsWith('|')) {
+      if (enTabla && trim === '') {
+        enTabla = false;
+        idxNum = -1;
+      }
+      continue;
+    }
+    const celdas = trim.split('|').map(c => c.trim()).filter(c => c !== '');
+
+    if (idxNum === -1) {
+      const low = celdas.map(c => c.toLowerCase());
+      const n = low.findIndex(c => c === '#' || c === 'id');
+      const no = low.findIndex(c => c === 'entregable' || c === 'nombre');
+      const de = low.findIndex(c => c === 'descripción' || c === 'descripcion');
+      const re = low.findIndex(c => c.includes('requisitos') || c.includes('cubiertos'));
+      const es = low.findIndex(c => c === 'estado');
+      if (n !== -1 && no !== -1 && es !== -1) {
+        idxNum = n; idxNombre = no; idxDesc = de; idxReqs = re; idxEstado = es;
+        enTabla = true;
+      }
+      continue;
+    }
+
+    if (celdas.every(c => /^-+$/.test(c.replace(/:/g, '')))) continue;
+    if (!enTabla) continue;
+
+    const numEntregable = celdas[idxNum];
+    if (!numEntregable) continue;
+
+    entregables.push({
+      id: numEntregable,
+      nombre: celdas[idxNombre] || null,
+      descripcion: idxDesc !== -1 ? (celdas[idxDesc] || null) : null,
+      requisitos: idxReqs !== -1
+        ? (celdas[idxReqs] || '').split(',').map(s => s.trim()).filter(Boolean)
+        : [],
+      estado: normalizarEstado(celdas[idxEstado]),
+    });
+  }
+
+  return entregables;
+}
+
+function parsearChecklistCriterios(seccion) {
+  // Captura solo el bloque "Criterios de verificación" si existe
+  const idx = seccion.toLowerCase().indexOf('criterios de verificación');
+  if (idx === -1) return [];
+  const subseccion = seccion.slice(idx);
+  // Cortar en la siguiente sub-sección o el final
+  const finIdx = subseccion.search(/\n###?\s+/m);
+  const recorte = finIdx === -1 ? subseccion : subseccion.slice(0, finIdx);
+
+  const criterios = [];
+  const re = /^\s*-\s*\[(x| )\]\s+(.+?)$/gim;
+  let m;
+  while ((m = re.exec(recorte)) !== null) {
+    criterios.push({
+      cumplido: m[1].toLowerCase() === 'x',
+      descripcion: m[2].trim(),
+    });
+  }
+  return criterios;
+}
+
+function normalizarEstado(estadoRaw) {
+  if (!estadoRaw) return 'pendiente';
+  const lower = estadoRaw.toLowerCase().trim();
+
+  if (lower.includes('complet')) return 'completado';
+  if (lower.includes('done') || lower.includes('hecho')) return 'completado';
+  if (lower.includes('progreso') || lower.includes('progress') || lower.includes('curso')) {
+    return 'en_progreso';
+  }
+  if (lower.includes('spec') && lower.includes('listo')) return 'spec_listo';
+  if (lower.includes('bloque') || lower.includes('block')) return 'bloqueado';
+  if (lower.includes('pendiente') || lower.includes('pending')) return 'pendiente';
+
+  return 'pendiente'; // default conservador
+}
+
+function esFecha(s) {
+  return /^\d{4}-\d{2}-\d{2}/.test(s);
+}
+
+// ─── Enriquecimiento desde .planning/fases/ ──────────────────────────────────
+
+/**
+ * Para cada fase, intenta enriquecer con info de:
+ *   .planning/fases/0N-PLAN.md     → existe + estado
+ *   .planning/fases/0N-RESUMEN.md  → completada
+ *   .planning/fases/0N-CONTEXTO.md → discutida
+ */
+function enriquecerDesdeFases(fases, opciones = {}) {
+  // CWD dinámico — recalcula al llamar, no al require, para que los tests con
+  // process.chdir() funcionen sin requerir reload del módulo.
+  const cwd = opciones.cwd || process.cwd();
+  const fasesDir = path.join(cwd, '.planning', 'fases');
+  if (!fs.existsSync(fasesDir)) return fases;
+
+  const archivos = fs.readdirSync(fasesDir);
+
+  for (const fase of fases) {
+    const num = fase.numero.toString().padStart(2, '0');
+
+    fase.artefactos = {
+      contexto_md: archivos.includes(`${num}-CONTEXTO.md`)
+        ? `.planning/fases/${num}-CONTEXTO.md` : null,
+      plan_md: archivos.includes(`${num}-PLAN.md`)
+        ? `.planning/fases/${num}-PLAN.md` : null,
+      resumen_md: archivos.includes(`${num}-RESUMEN.md`)
+        ? `.planning/fases/${num}-RESUMEN.md` : null,
+    };
+
+    // Si tiene PLAN.md, intentar leer su frontmatter `estado:` para refinar
+    if (fase.artefactos.plan_md) {
+      const planPath = path.join(cwd, fase.artefactos.plan_md);
+      try {
+        const planContent = fs.readFileSync(planPath, 'utf-8');
+        const frontMatch = planContent.match(/^---\s*\n([\s\S]*?)\n---/);
+        if (frontMatch) {
+          const fm = frontMatch[1];
+          const estadoPlan = (fm.match(/^estado:\s*(.+)$/m) || [])[1];
+          if (estadoPlan) {
+            const estadoPlanLow = estadoPlan.trim().toLowerCase();
+            fase.plan_estado = estadoPlanLow;
+            // Si el PLAN está aprobado pero el roadmap dice "pendiente",
+            // refinar a "en_progreso" porque ya pasó la planeación.
+            if (estadoPlanLow === 'aprobado' && fase.estado === 'pendiente') {
+              fase.estado = 'en_progreso';
+            }
+          }
+        }
+      } catch { /* no bloquear si el PLAN tiene formato no esperado */ }
+    }
+
+    // Si tiene RESUMEN.md, asumir completada (a menos que HOJA-RUTA diga otra cosa explícita)
+    if (fase.artefactos.resumen_md && fase.estado !== 'bloqueado') {
+      fase.estado = 'completado';
+    }
+  }
+
+  return fases;
+}
+
+// ─── Generación del JSON canónico ────────────────────────────────────────────
+
+function generarFeatureList(fases) {
+  const ahora = new Date().toISOString();
+  const totales = {
+    fases: fases.length,
+    completadas: fases.filter(f => f.estado === 'completado').length,
+    en_progreso: fases.filter(f => f.estado === 'en_progreso').length,
+    pendientes: fases.filter(f => f.estado === 'pendiente').length,
+    bloqueadas: fases.filter(f => f.estado === 'bloqueado').length,
+    spec_listas: fases.filter(f => f.estado === 'spec_listo').length,
+  };
+
+  return {
+    schema: 'swl-feature-list/v1',
+    generado_en: ahora,
+    fuente: '.planning/HOJA-RUTA.md',
+    nota: 'Derivado automáticamente. HOJA-RUTA.md es la fuente de verdad. Regenerar con `node scripts/derivar-feature-list.js`.',
+    totales,
+    fases,
+  };
+}
+
+// ─── Comparación para --check ────────────────────────────────────────────────
+
+function compararConDisco(generado, rutaOut) {
+  if (!fs.existsSync(rutaOut)) {
+    return { iguales: false, razon: `${rutaOut} no existe` };
+  }
+  let actual;
+  try {
+    actual = JSON.parse(fs.readFileSync(rutaOut, 'utf-8'));
+  } catch (err) {
+    return { iguales: false, razon: `JSON existente está corrupto: ${err.message}` };
+  }
+
+  // Comparar ignorando `generado_en` (timestamp cambia siempre)
+  const a = { ...generado, generado_en: '_' };
+  const b = { ...actual, generado_en: '_' };
+
+  const aStr = JSON.stringify(a);
+  const bStr = JSON.stringify(b);
+
+  if (aStr === bStr) return { iguales: true };
+  return {
+    iguales: false,
+    razon: 'Contenido difiere. Regenerar con `node scripts/derivar-feature-list.js`.',
+  };
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+function parsearArgs(argv) {
+  const args = { out: DEFAULT_OUT, check: false, verbose: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check' || a === '-c') args.check = true;
+    else if (a === '--verbose' || a === '-v') args.verbose = true;
+    else if (a === '--out' || a === '-o') args.out = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      console.log('Uso: derivar-feature-list.js [--out <path>] [--check] [--verbose]');
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+function main() {
+  const args = parsearArgs(process.argv);
+
+  if (!fs.existsSync(HOJA_RUTA)) {
+    console.error('[derivar-feature-list] .planning/HOJA-RUTA.md no encontrado.');
+    console.error('  Inicializa con `/swl:nuevo-proyecto` o `/swl:adoptar-proyecto` primero.');
+    process.exit(1);
+  }
+
+  const contenido = fs.readFileSync(HOJA_RUTA, 'utf-8');
+  let fases;
+  try {
+    fases = parsearHojaRuta(contenido);
+    fases = enriquecerDesdeFases(fases);
+  } catch (err) {
+    console.error(`[derivar-feature-list] Error de parsing: ${err.message}`);
+    process.exit(3);
+  }
+
+  if (fases.length === 0 && args.verbose) {
+    console.log('[derivar-feature-list] No se detectaron fases en HOJA-RUTA.md.');
+    console.log('  El JSON se genera vacío (válido para proyectos recién inicializados).');
+  }
+
+  const generado = generarFeatureList(fases);
+
+  if (args.check) {
+    const cmp = compararConDisco(generado, args.out);
+    if (cmp.iguales) {
+      if (args.verbose) console.log(`[derivar-feature-list] OK — ${args.out} está sincronizado.`);
+      process.exit(0);
+    }
+    console.error(`[derivar-feature-list] DRIFT: ${cmp.razon}`);
+    process.exit(2);
+  }
+
+  fs.writeFileSync(args.out, JSON.stringify(generado, null, 2), 'utf-8');
+  if (args.verbose) {
+    console.log(`[derivar-feature-list] Generado ${args.out}`);
+    console.log(`  ${generado.totales.fases} fases | ${generado.totales.completadas} completadas | ${generado.totales.en_progreso} en progreso | ${generado.totales.pendientes} pendientes`);
+  } else {
+    console.log(`[derivar-feature-list] ${args.out} actualizado (${generado.totales.fases} fases)`);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parsearHojaRuta,
+  enriquecerDesdeFases,
+  generarFeatureList,
+  normalizarEstado,
+};

package/scripts/doctor.js

@@ -335,10 +335,37 @@ async function doctor(opciones = {}) {
       const { detectarStack, filtrarReglasPorStack } = require('./lib/detectar-stack');
       const resolucion = resolverPerfil(estado.perfil, { target: estado.target });
 
-      // Aplicar el mismo filtro de reglas por stack que usa el instalador
-      const stackDetectado = detectarStack(cwd);
-      const filtrado = filtrarReglasPorStack(resolucion.archivos, stackDetectado);
-      resolucion.archivos = filtrado.archivos;
+      // Fix v1.4.3: usar el contexto de filtrado persistido al momento del
+      // install (allLangs, stackInstalado) en lugar de recalcular desde el cwd
+      // actual del doctor. Si el estado no lo persiste (instalación previa a
+      // v1.4.3), inferirlo desde los archivos realmente instalados.
+      let stackParaFiltro;
+      let omitirFiltro = false;
+      if (estado.allLangs === true) {
+        omitirFiltro = true;
+      } else if (Array.isArray(estado.stackInstalado)) {
+        stackParaFiltro = new Set(estado.stackInstalado);
+      } else {
+        // Backward compat: instalaciones previas a v1.4.3 no persisten contexto
+        // de filtrado. Inferirlo desde los archivos realmente instalados:
+        // cada subdir bajo reglas/lenguajes/X/ corresponde a un lenguaje
+        // detectado o a --all-langs activo al momento del install.
+        // El campo persistido en estado es `origen` (ruta relativa al paquete).
+        const langsInstalados = new Set();
+        for (const archivo of estado.archivosInstalados) {
+          const ruta = (archivo.origen || '').replace(/\\/g, '/');
+          if (!ruta.startsWith('reglas/lenguajes/')) continue;
+          const resto = ruta.slice('reglas/lenguajes/'.length);
+          const lang = resto.split('/')[0];
+          if (lang) langsInstalados.add(lang);
+        }
+        stackParaFiltro = langsInstalados;
+      }
+
+      if (!omitirFiltro) {
+        const filtrado = filtrarReglasPorStack(resolucion.archivos, stackParaFiltro);
+        resolucion.archivos = filtrado.archivos;
+      }
 
       // Contar esperados por tipo (solo tipos principales)
       const tiposPrincipales = ['agentes', 'habilidades', 'comandos', 'reglas'];

package/scripts/instalador.js

@@ -411,6 +411,11 @@ async function install(opciones) {
     perfil,
     rutaBase: rutas.base,
     global: esGlobal,
+    // Persistir contexto de filtrado de reglas-lenguajes para que doctor
+    // verifique conteos contra el filtro real al instalar (no recalcule
+    // desde el cwd actual del doctor). Fix v1.4.3.
+    allLangs: allLangs === true,
+    stackInstalado: stackDetectado instanceof Set ? [...stackDetectado] : null,
   });
 
   let instalados = 0;
@@ -447,6 +452,11 @@ async function install(opciones) {
     }
   }
 
+  // Cargar transformador del target ANTES del loop de instalación —
+  // Sub-fase 11.5: permite que instalarArchivo invoque transformarAgente
+  // por archivo para targets que cambian formato (ej. codex .md → .toml).
+  const transformadorTarget = obtenerTransformador(target, runtime);
+
   // Instalar archivos core
   for (const archivo of resolucion.archivos) {
     try {
@@ -457,6 +467,7 @@ async function install(opciones) {
         estado,
         syncMode,
         flatNaming,
+        transformador: transformadorTarget,
       });
       if (resultado.instalado) {
         registrarArchivo(estado, {
@@ -612,6 +623,13 @@ async function install(opciones) {
         // transformador Claude pueda detectar stack/comandos/framework.
         // Otros transformadores ignoran este campo.
         dirProyecto: process.cwd(),
+        // ADR-0019 Sub-fase 1: el transformador Codex necesita saber el scope para
+        // resolver dirBase (~/.codex/ vs cwd) y registrar el MCP server.
+        // El runtime trae los paths absolutos calculados por detectar-runtime.js.
+        esGlobal,
+        dirRuntimeGlobal: runtime.global,
+        withMcp: Boolean(opciones.with_mcp) && !opciones.no_mcp,
+        swlBinPath: path.join(RAIZ_PKG, 'bin', 'swl-mcp-server.js'),
       });
 
       if (instrucciones) {
@@ -628,6 +646,7 @@ async function install(opciones) {
           console.log('  = CLAUDE.md no modificado (--no-claudemd)');
         } else if (instrucciones.merge && instrucciones.merge.tipo === 'marcadores') {
           // Merge idempotente con marcadores — preserva contenido del usuario.
+          // Aplica a CLAUDE.md (Claude Code) y AGENTS.md (Codex CLI) — ADR-0019 Sub-fase 1.
           if (!fs.existsSync(dirInstrucciones)) {
             fs.mkdirSync(dirInstrucciones, { recursive: true });
           }
@@ -637,12 +656,13 @@ async function install(opciones) {
             endTag:      instrucciones.merge.endTag,
             beginPrefix: instrucciones.merge.beginPrefix,
           });
+          const nombreArchivo = instrucciones.rutaRelativa;
           const etiqueta = {
-            'creado':       '+ CLAUDE.md creado con bloque SWL',
-            'append':       '+ Bloque SWL agregado al final de CLAUDE.md (contenido del usuario preservado)',
-            'reemplazado':  '* Bloque SWL actualizado en CLAUDE.md (contenido del usuario preservado)',
-            'sin-cambios':  '= CLAUDE.md ya tenía el bloque SWL actualizado',
-            'error':        '! Error al fusionar CLAUDE.md',
+            'creado':       `+ ${nombreArchivo} creado con bloque SWL`,
+            'append':       `+ Bloque SWL agregado al final de ${nombreArchivo} (contenido del usuario preservado)`,
+            'reemplazado':  `* Bloque SWL actualizado en ${nombreArchivo} (contenido del usuario preservado)`,
+            'sin-cambios':  `= ${nombreArchivo} ya tenía el bloque SWL actualizado`,
+            'error':        `! Error al fusionar ${nombreArchivo}`,
           }[resMerge.accion] || `${resMerge.accion} ${resMerge.archivo}`;
           console.log(`  ${etiqueta}${resMerge.detalle ? ': ' + resMerge.detalle : ''}`);
           registrarArchivo(estado, {
@@ -850,6 +870,33 @@ function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
 
   let nombreArchivo = path.basename(archivo.origen);
 
+  // Sub-fase 11.5 v1.5.0: para tipo 'agentes', aplicar transformarAgente del
+  // transformador del target ANTES de la copia. Permite que codex emita TOML
+  // (.toml) en lugar del .md original, o que cursor normalice el frontmatter.
+  // Si transformarAgente devuelve `consolidar: true`, saltar — el archivo
+  // se incluirá en el archivoPrincipal (AGENTS.md) generado más adelante.
+  let contenidoTransformado = null;
+  if (archivo.tipo === 'agentes' && opciones.transformador && typeof opciones.transformador.transformarAgente === 'function') {
+    try {
+      const original = fs.readFileSync(archivo.origen, 'utf-8');
+      const t = opciones.transformador.transformarAgente(original, { nombreArchivo });
+      if (t && t.consolidar === true) {
+        // El transformador del target prefiere consolidar este agente en el
+        // archivoPrincipal en lugar de tener archivo individual. No instalar aquí.
+        return { instalado: false, razon: 'consolidado en archivoPrincipal' };
+      }
+      if (t && typeof t.contenido === 'string') {
+        contenidoTransformado = t.contenido;
+        if (t.rutaRelativa) {
+          // Usar el basename del rutaRelativa devuelto (puede cambiar extensión .md → .toml)
+          nombreArchivo = path.basename(t.rutaRelativa);
+        }
+      }
+    } catch (err) {
+      console.log(`  ! Transformación de agente falló (${err.message}), copia literal del .md`);
+    }
+  }
+
   // Flat naming: convierte rutas jerárquicas en nombres planos con __
   // Ejemplo: habilidades/build-errors-python → build-errors-python (sin cambio, ya es plano)
   // Ejemplo: reglas/lenguajes/java/java-estilo.md → java__java-estilo.md
@@ -991,6 +1038,10 @@ function instalarArchivo(archivo, rutas, runtime, opciones = {}) {
     // Copy mode (default) o fallback de symlink
     if (stat.isDirectory()) {
       copiarDirectorio(archivo.origen, path.join(dirDestino, nombreArchivo));
+    } else if (contenidoTransformado !== null) {
+      // Sub-fase 11.5: el transformador del target reescribió el contenido
+      // (ej. codex .md → .toml). Escribir el contenido transformado.
+      fs.writeFileSync(destino, contenidoTransformado, 'utf-8');
     } else {
       fs.copyFileSync(archivo.origen, destino);
     }