@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/derivar-feature-list.js

@@ -1,489 +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,
-};
+#!/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,
+};