@saulwade/swl-ses 2.2.3 → 2.3.0

package/scripts/verificar-trazabilidad.js

@@ -1,298 +1,329 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * verificar-trazabilidad.js — Valida la cadena REQ→T→commit→test de una fase (G4).
- *
- * Uso:
- *   node scripts/verificar-trazabilidad.js --fase=10 [--solo-plan] [--json]
- *
- * Fuentes:
- *   - REQ-NN:  `.planning/fases/NN-CONTEXTO.md` § Criterios de aceptación
- *              (definiciones `**REQ-NN**:` o `REQ-NN:`; los marcados RETIRADO
- *              se excluyen del universo exigible)
- *   - T-NN:    `.planning/fases/NN-PLAN.md` — campo `**Verifica REQ**: ...`
- *              por tarea `### T-NN:`
- *   - Commits: `git log` — footer `Refs: REQ-NN[, REQ-MM]`
- *   - Tests:   archivos de test versionados (git ls-files + clasificador de
- *              calidad-pre-commit) con marker `verifica: REQ-NN`
- *
- * Exit codes:
- *   0 — cadena completa, o CONTEXTO legacy sin REQ-IDs (gracia, con nota)
- *   1 — huérfanos detectados (REQ sin tarea / sin commit / sin test)
- *   2 — error de invocación o parseo (fase inexistente, args inválidos)
- *
- * `--solo-plan`: valida únicamente la matriz REQ×T (lo usa /swl:aprobar-plan,
- * donde commits y tests aún no existen).
- *
- * Zero-deps. Espejo estructural de verificar-release.js (gates + exit codes).
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const LIMITE_COMMITS = 300;
-
-// ─── Parseo de fuentes ──────────────────────────────────────────────────────
-
-/**
- * Extrae definiciones REQ-NN del CONTEXTO.
- * Método de verificación por REQ (patrón requirements engineering):
- *   - default `test` — exige test con marker `verifica: REQ-NN`
- *   - `(verificación: inspección)` en el criterio — satisfecho por prosa/docs/grep;
- *     exige tarea y commit, pero NO test automatizado.
- * @returns {{activos: string[], retirados: string[], metodo: Object<string,string>}}
- */
-function extraerReqs(contextoTexto) {
-  const activos = new Set();
-  const retirados = new Set();
-  const metodo = {};
-  // Definición: línea con `**REQ-NN**:` o `REQ-NN:` (con bullet opcional).
-  // El criterio puede continuar en líneas siguientes indentadas — se capturan
-  // hasta la próxima definición para detectar la anotación de método.
-  // REQ-NN (legacy) o REQ-NN-MM (namespaceado por fase, DT-IDS-NAMESPACE).
-  // El grupo `(?:-\d{1,3})?` es greedy: en `REQ-12-01` captura el ID completo,
-  // nunca el prefijo `REQ-12` truncado.
-  const re = /^\s*(?:[-*]\s*)?\*{0,2}(REQ-\d{1,3}(?:-\d{1,3})?)\*{0,2}\s*:([\s\S]*?)(?=^\s*(?:[-*]\s*)?\*{0,2}REQ-\d|^#|\n\n|$(?![\s\S]))/gm;
-  let m;
-  while ((m = re.exec(contextoTexto)) !== null) {
-    const cuerpo = m[2];
-    if (/RETIRADO/i.test(cuerpo)) {
-      retirados.add(m[1]);
-      continue;
-    }
-    activos.add(m[1]);
-    metodo[m[1]] = /verificaci[oó]n:\s*inspecci[oó]n/i.test(cuerpo) ? 'inspeccion' : 'test';
-  }
-  return { activos: [...activos], retirados: [...retirados], metodo };
-}
-
-/** Extrae mapa tarea→REQs del PLAN. @returns {Map<string, string[]>} */
-function extraerMatrizPlan(planTexto) {
-  const tareas = new Map();
-  let tareaActual = null;
-  for (const linea of planTexto.split('\n')) {
-    const t = linea.match(/^#{2,4}\s*(T-\d{1,3})\s*:/);
-    if (t) {
-      tareaActual = t[1];
-      if (!tareas.has(tareaActual)) tareas.set(tareaActual, []);
-      continue;
-    }
-    // Solo la línea-campo cuenta (`- **Verifica REQ**: ...` al inicio, bullet
-    // opcional). Una descripción que cite `**Verifica REQ**:` en prosa NO debe
-    // contaminar la matriz ni ocultar huérfanos (ancla `^` obligatoria).
-    if (tareaActual && /^\s*(?:[-*]\s*)?\*\*Verifica REQ\*\*\s*:/i.test(linea)) {
-      const reqs = linea.match(/REQ-\d{1,3}(?:-\d{1,3})?/g) || [];
-      tareas.get(tareaActual).push(...reqs);
-    }
-  }
-  return tareas;
-}
-
-/** Commits con footer `Refs: REQ-NN`. @returns {Map<string, string[]>} REQ → hashes cortos */
-function extraerCommitsConRefs(cwd) {
-  const porReq = new Map();
-  let salida;
-  try {
-    salida = execFileSync(
-      'git',
-      ['log', `-${LIMITE_COMMITS}`, '--format=%h%x00%B%x01'],
-      { cwd, encoding: 'utf8', timeout: 10000 }
-    );
-  } catch (_) {
-    return porReq; // sin repo git o sin commits — el reporte lo refleja como gap
-  }
-  for (const bloque of salida.split('\x01')) {
-    const [hash, cuerpo] = bloque.split('\x00');
-    if (!hash || !cuerpo) continue;
-    const refs = cuerpo.match(/^Refs:\s*(.+)$/m);
-    if (!refs) continue;
-    for (const req of refs[1].match(/REQ-\d{1,3}(?:-\d{1,3})?/g) || []) {
-      if (!porReq.has(req)) porReq.set(req, []);
-      porReq.get(req).push(hash.trim());
-    }
-  }
-  return porReq;
-}
-
-/** Tests con marker `verifica: REQ-NN`. @returns {Map<string, string[]>} REQ → archivos */
-function extraerTestsConMarker(cwd) {
-  const porReq = new Map();
-  let esArchivoTest;
-  try {
-    ({ esArchivoTest } = require(path.join(__dirname, '..', 'hooks', 'calidad-pre-commit.js')));
-  } catch (_) {
-    esArchivoTest = (r) => /\.(test|spec)\.[jt]sx?$/.test(r) || /test_.*\.py$/.test(r);
-  }
-
-  let archivos = [];
-  try {
-    archivos = execFileSync('git', ['ls-files'], { cwd, encoding: 'utf8', timeout: 10000 })
-      .split('\n')
-      .map((l) => l.trim())
-      .filter(Boolean)
-      .filter(esArchivoTest);
-  } catch (_) {
-    return porReq;
-  }
-
-  for (const archivo of archivos) {
-    let contenido;
-    try {
-      contenido = fs.readFileSync(path.join(cwd, archivo), 'utf-8');
-    } catch (_) {
-      continue;
-    }
-    for (const m of contenido.matchAll(/verifica:\s*(REQ-\d{1,3}(?:-\d{1,3})?)/g)) {
-      const req = m[1];
-      if (!porReq.has(req)) porReq.set(req, []);
-      if (!porReq.get(req).includes(archivo)) porReq.get(req).push(archivo);
-    }
-  }
-  return porReq;
-}
-
-// ─── Validación ─────────────────────────────────────────────────────────────
-
-function validarFase({ cwd, fase, soloPlan }) {
-  const nn = String(Number(fase)).padStart(2, '0');
-  const contextoPath = path.join(cwd, '.planning', 'fases', `${nn}-CONTEXTO.md`);
-  if (!fs.existsSync(contextoPath)) {
-    return { error: `No existe ${path.relative(cwd, contextoPath)}`, exit: 2 };
-  }
-
-  const { activos, retirados, metodo } = extraerReqs(fs.readFileSync(contextoPath, 'utf-8'));
-  if (activos.length === 0) {
-    return {
-      fase: nn,
-      legacy: true,
-      nota: 'CONTEXTO sin REQ-IDs — trazabilidad no exigible (gracia legacy, fases pre-10)',
-      exit: 0,
-    };
-  }
-
-  const planPath = path.join(cwd, '.planning', 'fases', `${nn}-PLAN.md`);
-  const matrizTareas = fs.existsSync(planPath)
-    ? extraerMatrizPlan(fs.readFileSync(planPath, 'utf-8'))
-    : new Map();
-
-  const reqATareas = new Map(activos.map((r) => [r, []]));
-  const tareasSinReq = [];
-  for (const [tarea, reqs] of matrizTareas) {
-    if (reqs.length === 0) tareasSinReq.push(tarea);
-    for (const req of reqs) {
-      if (reqATareas.has(req)) reqATareas.get(req).push(tarea);
-    }
-  }
-
-  const commits = soloPlan ? new Map() : extraerCommitsConRefs(cwd);
-  const tests = soloPlan ? new Map() : extraerTestsConMarker(cwd);
-
-  const validaciones = {
-    req_sin_tarea: activos.filter((r) => (reqATareas.get(r) || []).length === 0),
-    req_sin_commit: soloPlan ? [] : activos.filter((r) => !(commits.get(r) || []).length),
-    req_sin_test: soloPlan
-      ? []
-      : activos.filter((r) => metodo[r] === 'test' && !(tests.get(r) || []).length),
-    tarea_sin_req: tareasSinReq, // informativo, no rompe
-  };
-
-  const trazabilidad = {};
-  for (const req of activos) {
-    trazabilidad[req] = {
-      metodo: metodo[req],
-      tareas: reqATareas.get(req) || [],
-      commits: commits.get(req) || [],
-      tests: tests.get(req) || [],
-    };
-  }
-
-  const huerfanos =
-    validaciones.req_sin_tarea.length +
-    validaciones.req_sin_commit.length +
-    validaciones.req_sin_test.length;
-
-  return {
-    fase: nn,
-    legacy: false,
-    soloPlan: Boolean(soloPlan),
-    reqs: activos,
-    retirados,
-    trazabilidad,
-    validaciones,
-    exit: huerfanos > 0 ? 1 : 0,
-  };
-}
-
-// ─── Reporte ────────────────────────────────────────────────────────────────
-
-function imprimirReporte(r) {
-  if (r.error) {
-    console.error(`ERROR: ${r.error}`);
-    return;
-  }
-  if (r.legacy) {
-    console.log(`Fase ${r.fase}: ${r.nota}. Exit 0.`);
-    return;
-  }
-  console.log(`Trazabilidad REQ→T→commit→test — Fase ${r.fase}${r.soloPlan ? ' (--solo-plan: matriz REQ×T)' : ''}`);
-  console.log('');
-  for (const req of r.reqs) {
-    const t = r.trazabilidad[req];
-    const partes = [`tareas: ${t.tareas.join(', ') || '—'}`];
-    if (!r.soloPlan) {
-      partes.push(`commits: ${t.commits.join(', ') || '—'}`);
-      partes.push(t.metodo === 'inspeccion' ? 'verificación: inspección' : `tests: ${t.tests.join(', ') || '—'}`);
-    }
-    console.log(`  ${req} → ${partes.join(' | ')}`);
-  }
-  if (r.retirados.length) console.log(`  Retirados (no exigibles): ${r.retirados.join(', ')}`);
-  console.log('');
-
-  const v = r.validaciones;
-  const gaps = [];
-  if (v.req_sin_tarea.length) gaps.push(`REQ sin tarea: ${v.req_sin_tarea.join(', ')}`);
-  if (v.req_sin_commit.length) gaps.push(`REQ sin commit (footer Refs:): ${v.req_sin_commit.join(', ')}`);
-  if (v.req_sin_test.length) gaps.push(`REQ sin test (marker verifica:): ${v.req_sin_test.join(', ')}`);
-
-  if (gaps.length) {
-    console.log('HUÉRFANOS DETECTADOS:');
-    for (const g of gaps) console.log(`  ✗ ${g}`);
-  } else {
-    console.log('✓ Cadena de trazabilidad completa: 0 huérfanos.');
-  }
-  if (v.tarea_sin_req.length) {
-    console.log(`  (info) Tareas sin REQ declarado: ${v.tarea_sin_req.join(', ')} — válido para infraestructura/refactor`);
-  }
-}
-
-// ─── CLI ────────────────────────────────────────────────────────────────────
-
-function main() {
-  const args = process.argv.slice(2);
-  const faseArg = args.find((a) => a.startsWith('--fase='));
-  if (!faseArg || !/^\d+$/.test(faseArg.split('=')[1] || '')) {
-    console.error('Uso: node scripts/verificar-trazabilidad.js --fase=N [--solo-plan] [--json]');
-    process.exit(2);
-  }
-
-  const resultado = validarFase({
-    cwd: process.cwd(),
-    fase: faseArg.split('=')[1],
-    soloPlan: args.includes('--solo-plan'),
-  });
-
-  if (args.includes('--json')) {
-    console.log(JSON.stringify(resultado, null, 2));
-  } else {
-    imprimirReporte(resultado);
-  }
-  process.exit(resultado.exit);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { extraerReqs, extraerMatrizPlan, extraerCommitsConRefs, extraerTestsConMarker, validarFase, main };
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verificar-trazabilidad.js — Valida la cadena REQ→T→commit→test de una fase (G4).
+ *
+ * Uso:
+ *   node scripts/verificar-trazabilidad.js --fase=10 [--solo-plan] [--json]
+ *
+ * Fuentes:
+ *   - REQ-NN:  `.planning/fases/NN-CONTEXTO.md` § Criterios de aceptación
+ *              (definiciones `**REQ-NN**:` o `REQ-NN:`; los marcados RETIRADO
+ *              se excluyen del universo exigible)
+ *   - T-NN:    `.planning/fases/NN-PLAN.md` — campo `**Verifica REQ**: ...`
+ *              por tarea `### T-NN:`
+ *   - Commits: `git log` — footer `Refs: REQ-NN[, REQ-MM]`
+ *   - Tests:   archivos de test versionados (git ls-files + clasificador de
+ *              calidad-pre-commit) con marker `verifica: REQ-NN`
+ *
+ * Exit codes:
+ *   0 — cadena completa, o CONTEXTO legacy sin REQ-IDs (gracia, con nota)
+ *   1 — huérfanos detectados (REQ sin tarea / sin commit / sin test)
+ *   2 — error de invocación o parseo (fase inexistente, args inválidos)
+ *
+ * `--solo-plan`: valida únicamente la matriz REQ×T (lo usa /swl:aprobar-plan,
+ * donde commits y tests aún no existen).
+ *
+ * Zero-deps. Espejo estructural de verificar-release.js (gates + exit codes).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const LIMITE_COMMITS = 300;
+
+// ─── Parseo de fuentes ──────────────────────────────────────────────────────
+
+/**
+ * Extrae definiciones REQ-NN del CONTEXTO.
+ * Método de verificación por REQ (patrón requirements engineering):
+ *   - default `test` — exige test con marker `verifica: REQ-NN`
+ *   - `(verificación: inspección)` en el criterio — satisfecho por prosa/docs/grep;
+ *     exige tarea y commit, pero NO test automatizado.
+ * @returns {{activos: string[], retirados: string[], metodo: Object<string,string>}}
+ */
+function extraerReqs(contextoTexto) {
+  const activos = new Set();
+  const retirados = new Set();
+  const metodo = {};
+  // Definición: línea con `**REQ-NN**:` o `REQ-NN:` (con bullet opcional).
+  // El criterio puede continuar en líneas siguientes indentadas — se capturan
+  // hasta la próxima definición para detectar la anotación de método.
+  // REQ-NN (legacy) o REQ-NN-MM (namespaceado por fase, DT-IDS-NAMESPACE).
+  // El grupo `(?:-\d{1,3})?` es greedy: en `REQ-12-01` captura el ID completo,
+  // nunca el prefijo `REQ-12` truncado.
+  const re = /^\s*(?:[-*]\s*)?\*{0,2}(REQ-\d{1,3}(?:-\d{1,3})?)\*{0,2}\s*:([\s\S]*?)(?=^\s*(?:[-*]\s*)?\*{0,2}REQ-\d|^#|\n\n|$(?![\s\S]))/gm;
+  let m;
+  while ((m = re.exec(contextoTexto)) !== null) {
+    const cuerpo = m[2];
+    if (/RETIRADO/i.test(cuerpo)) {
+      retirados.add(m[1]);
+      continue;
+    }
+    activos.add(m[1]);
+    metodo[m[1]] = /verificaci[oó]n:\s*inspecci[oó]n/i.test(cuerpo) ? 'inspeccion' : 'test';
+  }
+  return { activos: [...activos], retirados: [...retirados], metodo };
+}
+
+/** Extrae mapa tarea→REQs del PLAN. @returns {Map<string, string[]>} */
+function extraerMatrizPlan(planTexto) {
+  const tareas = new Map();
+  let tareaActual = null;
+  for (const linea of planTexto.split('\n')) {
+    const t = linea.match(/^#{2,4}\s*(T-\d{1,3})\s*:/);
+    if (t) {
+      tareaActual = t[1];
+      if (!tareas.has(tareaActual)) tareas.set(tareaActual, []);
+      continue;
+    }
+    // Solo la línea-campo cuenta (`- **Verifica REQ**: ...` al inicio, bullet
+    // opcional). Una descripción que cite `**Verifica REQ**:` en prosa NO debe
+    // contaminar la matriz ni ocultar huérfanos (ancla `^` obligatoria).
+    if (tareaActual && /^\s*(?:[-*]\s*)?\*\*Verifica REQ\*\*\s*:/i.test(linea)) {
+      const reqs = linea.match(/REQ-\d{1,3}(?:-\d{1,3})?/g) || [];
+      tareas.get(tareaActual).push(...reqs);
+    }
+  }
+  return tareas;
+}
+
+/**
+ * Detecta headers de tarea malformados que el parser de la matriz NO reconoce.
+ * El parser (`extraerMatrizPlan`) exige `### T-NN:` (2-4 `#`, dos puntos tras
+ * el ID). Un header como `#### T-01 — Foo` (em-dash) o `# T-01:` (un solo `#`)
+ * no matchea: la tarea no se registra y sus REQ salen huérfanos sin causa
+ * visible. Esta detección es warn-only — explica el porqué del huérfano, no
+ * cambia el exit code (patrón de introducción de gate warn-only, ADR-0034/0035).
+ * @returns {{linea:number, texto:string}[]}
+ */
+function detectarHeadersMalformados(planTexto) {
+  const malformados = [];
+  const canonico = /^#{2,4}\s*T-\d{1,3}\s*:/;
+  // "Parece header de tarea": cualquier nivel de heading que arranque con T-NN.
+  const pareceTarea = /^#{1,6}\s*T-\d{1,3}\b/;
+  const lineas = planTexto.split('\n');
+  for (let i = 0; i < lineas.length; i++) {
+    if (pareceTarea.test(lineas[i]) && !canonico.test(lineas[i])) {
+      malformados.push({ linea: i + 1, texto: lineas[i].trim() });
+    }
+  }
+  return malformados;
+}
+
+/** Commits con footer `Refs: REQ-NN`. @returns {Map<string, string[]>} REQ → hashes cortos */
+function extraerCommitsConRefs(cwd) {
+  const porReq = new Map();
+  let salida;
+  try {
+    salida = execFileSync(
+      'git',
+      ['log', `-${LIMITE_COMMITS}`, '--format=%h%x00%B%x01'],
+      { cwd, encoding: 'utf8', timeout: 10000 }
+    );
+  } catch (_) {
+    return porReq; // sin repo git o sin commits — el reporte lo refleja como gap
+  }
+  for (const bloque of salida.split('\x01')) {
+    const [hash, cuerpo] = bloque.split('\x00');
+    if (!hash || !cuerpo) continue;
+    const refs = cuerpo.match(/^Refs:\s*(.+)$/m);
+    if (!refs) continue;
+    for (const req of refs[1].match(/REQ-\d{1,3}(?:-\d{1,3})?/g) || []) {
+      if (!porReq.has(req)) porReq.set(req, []);
+      porReq.get(req).push(hash.trim());
+    }
+  }
+  return porReq;
+}
+
+/** Tests con marker `verifica: REQ-NN`. @returns {Map<string, string[]>} REQ → archivos */
+function extraerTestsConMarker(cwd) {
+  const porReq = new Map();
+  let esArchivoTest;
+  try {
+    ({ esArchivoTest } = require(path.join(__dirname, '..', 'hooks', 'calidad-pre-commit.js')));
+  } catch (_) {
+    esArchivoTest = (r) => /\.(test|spec)\.[jt]sx?$/.test(r) || /test_.*\.py$/.test(r);
+  }
+
+  let archivos = [];
+  try {
+    archivos = execFileSync('git', ['ls-files'], { cwd, encoding: 'utf8', timeout: 10000 })
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .filter(esArchivoTest);
+  } catch (_) {
+    return porReq;
+  }
+
+  for (const archivo of archivos) {
+    let contenido;
+    try {
+      contenido = fs.readFileSync(path.join(cwd, archivo), 'utf-8');
+    } catch (_) {
+      continue;
+    }
+    for (const m of contenido.matchAll(/verifica:\s*(REQ-\d{1,3}(?:-\d{1,3})?)/g)) {
+      const req = m[1];
+      if (!porReq.has(req)) porReq.set(req, []);
+      if (!porReq.get(req).includes(archivo)) porReq.get(req).push(archivo);
+    }
+  }
+  return porReq;
+}
+
+// ─── Validación ─────────────────────────────────────────────────────────────
+
+function validarFase({ cwd, fase, soloPlan }) {
+  const nn = String(Number(fase)).padStart(2, '0');
+  const contextoPath = path.join(cwd, '.planning', 'fases', `${nn}-CONTEXTO.md`);
+  if (!fs.existsSync(contextoPath)) {
+    return { error: `No existe ${path.relative(cwd, contextoPath)}`, exit: 2 };
+  }
+
+  const { activos, retirados, metodo } = extraerReqs(fs.readFileSync(contextoPath, 'utf-8'));
+  if (activos.length === 0) {
+    return {
+      fase: nn,
+      legacy: true,
+      nota: 'CONTEXTO sin REQ-IDs — trazabilidad no exigible (gracia legacy, fases pre-10)',
+      exit: 0,
+    };
+  }
+
+  const planPath = path.join(cwd, '.planning', 'fases', `${nn}-PLAN.md`);
+  const planTexto = fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf-8') : '';
+  const matrizTareas = extraerMatrizPlan(planTexto);
+  const headersMalformados = detectarHeadersMalformados(planTexto);
+
+  const reqATareas = new Map(activos.map((r) => [r, []]));
+  const tareasSinReq = [];
+  for (const [tarea, reqs] of matrizTareas) {
+    if (reqs.length === 0) tareasSinReq.push(tarea);
+    for (const req of reqs) {
+      if (reqATareas.has(req)) reqATareas.get(req).push(tarea);
+    }
+  }
+
+  const commits = soloPlan ? new Map() : extraerCommitsConRefs(cwd);
+  const tests = soloPlan ? new Map() : extraerTestsConMarker(cwd);
+
+  const validaciones = {
+    req_sin_tarea: activos.filter((r) => (reqATareas.get(r) || []).length === 0),
+    req_sin_commit: soloPlan ? [] : activos.filter((r) => !(commits.get(r) || []).length),
+    req_sin_test: soloPlan
+      ? []
+      : activos.filter((r) => metodo[r] === 'test' && !(tests.get(r) || []).length),
+    tarea_sin_req: tareasSinReq, // informativo, no rompe
+    headers_malformados: headersMalformados, // warn-only: no cambia exit (ADR-0034/0035)
+  };
+
+  const trazabilidad = {};
+  for (const req of activos) {
+    trazabilidad[req] = {
+      metodo: metodo[req],
+      tareas: reqATareas.get(req) || [],
+      commits: commits.get(req) || [],
+      tests: tests.get(req) || [],
+    };
+  }
+
+  const huerfanos =
+    validaciones.req_sin_tarea.length +
+    validaciones.req_sin_commit.length +
+    validaciones.req_sin_test.length;
+
+  return {
+    fase: nn,
+    legacy: false,
+    soloPlan: Boolean(soloPlan),
+    reqs: activos,
+    retirados,
+    trazabilidad,
+    validaciones,
+    exit: huerfanos > 0 ? 1 : 0,
+  };
+}
+
+// ─── Reporte ────────────────────────────────────────────────────────────────
+
+function imprimirReporte(r) {
+  if (r.error) {
+    console.error(`ERROR: ${r.error}`);
+    return;
+  }
+  if (r.legacy) {
+    console.log(`Fase ${r.fase}: ${r.nota}. Exit 0.`);
+    return;
+  }
+  console.log(`Trazabilidad REQ→T→commit→test — Fase ${r.fase}${r.soloPlan ? ' (--solo-plan: matriz REQ×T)' : ''}`);
+  console.log('');
+  for (const req of r.reqs) {
+    const t = r.trazabilidad[req];
+    const partes = [`tareas: ${t.tareas.join(', ') || '—'}`];
+    if (!r.soloPlan) {
+      partes.push(`commits: ${t.commits.join(', ') || '—'}`);
+      partes.push(t.metodo === 'inspeccion' ? 'verificación: inspección' : `tests: ${t.tests.join(', ') || '—'}`);
+    }
+    console.log(`  ${req} → ${partes.join(' | ')}`);
+  }
+  if (r.retirados.length) console.log(`  Retirados (no exigibles): ${r.retirados.join(', ')}`);
+  console.log('');
+
+  const v = r.validaciones;
+  const gaps = [];
+  if (v.req_sin_tarea.length) gaps.push(`REQ sin tarea: ${v.req_sin_tarea.join(', ')}`);
+  if (v.req_sin_commit.length) gaps.push(`REQ sin commit (footer Refs:): ${v.req_sin_commit.join(', ')}`);
+  if (v.req_sin_test.length) gaps.push(`REQ sin test (marker verifica:): ${v.req_sin_test.join(', ')}`);
+
+  if (gaps.length) {
+    console.log('HUÉRFANOS DETECTADOS:');
+    for (const g of gaps) console.log(`  ✗ ${g}`);
+  } else {
+    console.log('✓ Cadena de trazabilidad completa: 0 huérfanos.');
+  }
+  if (v.tarea_sin_req.length) {
+    console.log(`  (info) Tareas sin REQ declarado: ${v.tarea_sin_req.join(', ')} — válido para infraestructura/refactor`);
+  }
+  if (v.headers_malformados && v.headers_malformados.length) {
+    console.log('');
+    console.log('⚠ WARN — headers de tarea malformados (la matriz REQ×T NO los parsea):');
+    for (const h of v.headers_malformados) console.log(`  línea ${h.linea}: ${h.texto}`);
+    console.log('  Formato esperado: `### T-NN:` (2-4 `#`, dos puntos tras el ID; no em-dash).');
+    console.log('  Si hay REQ huérfanos arriba, esta suele ser la causa. (warn-only, no bloquea)');
+  }
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  const faseArg = args.find((a) => a.startsWith('--fase='));
+  if (!faseArg || !/^\d+$/.test(faseArg.split('=')[1] || '')) {
+    console.error('Uso: node scripts/verificar-trazabilidad.js --fase=N [--solo-plan] [--json]');
+    process.exit(2);
+  }
+
+  const resultado = validarFase({
+    cwd: process.cwd(),
+    fase: faseArg.split('=')[1],
+    soloPlan: args.includes('--solo-plan'),
+  });
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(resultado, null, 2));
+  } else {
+    imprimirReporte(resultado);
+  }
+  process.exit(resultado.exit);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { extraerReqs, extraerMatrizPlan, detectarHeadersMalformados, extraerCommitsConRefs, extraerTestsConMarker, validarFase, main };