@saulwade/swl-ses 1.9.0 → 2.0.0

package/reglas/testing.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/vitest.config.{js,ts,mjs}"
+  - "**/playwright.config.{js,ts}"
+---
 # Regla: Testing — Next.js
 
 Probar Next.js con App Router requiere estrategia porque existen tres tipos de

package/reglas/tests-cleanup.md

@@ -1,3 +1,7 @@
+---
+paths:
+  - "**/tests/**"
+---
 # Regla: Cleanup obligatorio de directorios temporales en tests
 
 Esta regla es **OBLIGATORIA** y aplica a todo test Node.js del sistema SWL

package/reglas/usar-sistema-swl.md

@@ -78,7 +78,7 @@ de ejecutar.
 | Capturar aprendizaje recurrente | `/swl:aprender` → APRENDIZAJES.md → posible promoción a regla/skill |
 | Release con bump de versión | `/swl:release` (sincronización de ubicaciones de versión) |
 | Documentación viva post-feature | `documentador-swl` |
-| Diagnóstico del sistema | `/swl:salud` |
+| Diagnóstico del sistema | `/swl:status salud` |
 
 ### Para tareas de búsqueda y contexto
 

package/scripts/lib/gitignore-manifest.js

@@ -79,7 +79,13 @@ const ENTRADAS_BASE = [
   // artefactos del proyecto usuario.
   ".planning/evolution/",
   ".planning/auto-evolution/",
-  ".planning/locks/",
+  // locks/: contenido runtime ignorado (singleton-guard {pid,ts},
+  // fase-activa.json) EXCEPTO los plan-locks de G1 (*PLAN.md.lock), que son
+  // evidencia de aprobación versionable (audit trail SDD — aprobar-plan.md).
+  // Patrón `dir/*` + negación: git no re-incluye archivos si el DIRECTORIO
+  // está ignorado, por eso se ignora el contenido y no el dir.
+  ".planning/locks/*",
+  "!.planning/locks/*PLAN.md.lock",
   ".planning/user-profile/",
 
   // Instintos modificados automáticamente por hooks (degradacion-instintos.js)
@@ -87,6 +93,28 @@ const ENTRADAS_BASE = [
 
   // Base de datos de uso
   "usage.db",
+
+  // ── Runtime adicional: derivados regenerables, caches y telemetría ──
+  // Cobertura completada en Fase 09 tras auditar qué genera SWL en proyectos
+  // destino vs lo que ENTRADAS_BASE propagaba. Todo esto es output de runtime,
+  // regenerable, no editado por el equipo → no se commitea.
+  ".planning/feature-list.json",          // derivar-feature-list.js (derivado de HOJA-RUTA.md)
+  ".planning/loops/",                     // loop-telemetry.js (/swl:verificar, /swl:status loops)
+  ".planning/archive/",                   // rotar-audit-auto.js (audit/logs rotados y comprimidos)
+  ".planning/analysis/",                  // outputs de análisis
+  ".planning/graph.json",                 // code-review-graph (cache del grafo)
+  ".planning/graph-cache.json",           // code-review-graph (cache incremental)
+  ".planning/mcp-snapshot.json",          // /swl:status (smoke test MCP) / mcp-status
+  ".planning/skill-index.json",           // /swl:skill-search (índice FTS de skills)
+  ".planning/inventario-aviso-state.json", // throttle del aviso de inventario
+  ".planning/*.lock",                     // locks sueltos (ej. STATE.md.lock; el dir locks/ ya está arriba)
+
+  // Estado runtime de /swl:verificar --until-converge. Vive DENTRO de
+  // .planning/fases/, que SÍ contiene plantillas commiteadas
+  // (0N-CONTEXTO/PLAN/RESUMEN/VERIFICACION.md). Glob específico para ignorar
+  // SOLO el estado de convergencia, nunca esas plantillas.
+  ".planning/fases/*-converge-state.json",
+  ".planning/fases/*-converge-run-*.json",
 ];
 
 // Entradas adicionales por runtime (se agregan cuando install usa ese target)

package/scripts/lib/plan-lock.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * plan-lock.js — Firma y verificación de integridad de PLAN.md (Gate G1).
+ *
+ * Materializa el gate G1 del enforcement SDD (Fase 09, ADR de la Revisión
+ * Evolutiva 03): un PLAN aprobado vía `/swl:aprobar-plan` queda firmado con
+ * un SHA256 escrito en `.planning/locks/<basename>.lock`. `ejecutar-fase`
+ * recomputa ese hash al arrancar; un plan mutado tras la aprobación detiene
+ * la ejecución. Cierra el hueco "el plan puede mutar tras aprobación" que
+ * dejaba SDD en ~60%.
+ *
+ * Cláusula de gracia D-05 (compatibilidad legacy): un PLAN con
+ * `estado: aprobado` en su frontmatter pero SIN `.lock` correspondiente
+ * (los planes creados antes de la Fase 09) se considera `modo: "legacy"` y
+ * se ejecuta con advertencia, sin bloqueo. Solo los planes firmados vía
+ * `/swl:aprobar-plan` (post-Fase 09) exigen coincidencia de hash.
+ *
+ * MODELO DE AMENAZA (gate G1): el lock detecta MUTACIÓN ACCIDENTAL o no
+ * aprobada del PLAN tras su firma, y planes alterados por un agente que
+ * confabula. NO es un control criptográfico contra un adversario con acceso
+ * de escritura al repo — quien pueda commitear puede recalcular el SHA256 y
+ * re-firmar. La evidencia real de aprobación es `aprobadoPor:` + el commit del
+ * lock por `/swl:aprobar-plan` en el audit trail de git. El SHA256 solo detecta
+ * drift entre firma y verificación. (Verificación Fase 09, hallazgo S-6.)
+ *
+ * API:
+ *   firmarPlan(planPath, opciones?)  -> { ok, sha256, lockPath, archivo }
+ *   verificarPlan(planPath)          -> { ok, modo, motivo, ... }
+ *   resolverLockPath(planPath)       -> string (ruta del .lock esperado)
+ *
+ * Zero-dependencies. Compatible Windows (hash sobre buffer crudo). Node 18+.
+ *
+ * Origen: Fase 09 — enforcement SDD/TDD vNext H1, Slice 1.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo idéntico
+// al de scripts/generar-skills-lock.js para no acoplar a un layout fijo.
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require(path.join(__dirname, '..', '..', 'hooks', 'lib', 'atomic-write.js')));
+} catch {
+  atomicWriteSync = (p, c, e) => {
+    const dir = path.dirname(p);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, c, e);
+  };
+}
+
+const LOCK_VERSION = 1;
+
+// Basename válido de un PLAN de fase: `PLAN.md` o `0N-PLAN.md`. Evita que
+// `firmarPlan` produzca locks de archivos arbitrarios (falsearía el audit
+// trail de aprobación). Verificación Fase 09, hallazgo S-2.
+const PLAN_BASENAME_RE = /^(\d{2}-)?PLAN\.md$/;
+
+/**
+ * SHA256 de un buffer. Idéntico a scripts/generar-skills-lock.js:42-44.
+ * Se hashea el buffer crudo (no string utf8) para que el hash sea byte-exacto
+ * y detecte incluso cambios de fin de línea introducidos por un editor.
+ *
+ * @param {Buffer|string} data
+ * @returns {string} hex digest
+ */
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Extrae el campo `estado:` del frontmatter YAML del PLAN.
+ * Reutiliza el patrón CRLF-safe de scripts/generar-skills-lock.js:46-55.
+ *
+ * @param {string} contenido
+ * @returns {string|null} valor de `estado` o null si no hay frontmatter/campo
+ */
+function leerEstado(contenido) {
+  const m = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!m) return null;
+  for (const linea of m[1].split(/\r?\n/)) {
+    const kv = linea.match(/^estado:\s*(.*)$/);
+    if (kv) return kv[1].trim();
+  }
+  return null;
+}
+
+/**
+ * Resuelve el directorio `.planning/locks/` ascendiendo desde el PLAN hasta
+ * encontrar el directorio `.planning` ancestro. Robusto ante planes en
+ * `.planning/fases/0N-PLAN.md` o `.planning/PLAN.md`.
+ *
+ * Hardening S-1 (verificación Fase 09):
+ *   - Resuelve symlinks con `fs.realpathSync` antes de ascender, para que un
+ *     symlink plantado (`temp/.planning` → `/etc/.planning`) no permita escapar
+ *     del árbol real del proyecto.
+ *   - SIN fallback ciego: si no hay `.planning` ancestro, retorna `null` (antes
+ *     escribía `locks/` al lado del PLAN, en ubicación arbitraria). El caller
+ *     trata `null` como error explícito.
+ *
+ * @param {string} planPath
+ * @returns {string|null} ruta absoluta del directorio de locks, o null si no
+ *   hay `.planning` ancestro.
+ */
+function resolverLocksDir(planPath) {
+  let dir;
+  try {
+    dir = path.dirname(fs.realpathSync(path.resolve(planPath)));
+  } catch {
+    dir = path.dirname(path.resolve(planPath));
+  }
+  while (dir !== path.dirname(dir)) {
+    if (path.basename(dir) === '.planning') {
+      return path.join(dir, 'locks');
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Ruta del `.lock` esperado para un PLAN dado.
+ *
+ * @param {string} planPath
+ * @returns {string|null} ruta absoluta del archivo `.lock`, o null si el PLAN
+ *   no tiene un `.planning` ancestro.
+ */
+function resolverLockPath(planPath) {
+  const dir = resolverLocksDir(planPath);
+  return dir ? path.join(dir, `${path.basename(planPath)}.lock`) : null;
+}
+
+/**
+ * Firma un PLAN: computa su SHA256 y escribe el `.lock` correspondiente.
+ * Idempotente — re-firmar sobreescribe el lock (caso re-aprobación).
+ *
+ * @param {string} planPath
+ * @param {object} [opciones]
+ * @param {string} [opciones.firmadoPor='swl:aprobar-plan']
+ * @param {string} [opciones.firmadoEn] ISO timestamp; default new Date()
+ * @returns {{ok: boolean, sha256?: string, lockPath?: string, archivo?: string, motivo?: string}}
+ */
+function firmarPlan(planPath, opciones = {}) {
+  if (!fs.existsSync(planPath)) {
+    return { ok: false, motivo: `PLAN no existe: ${planPath}` };
+  }
+  const archivo = path.basename(planPath);
+  if (!PLAN_BASENAME_RE.test(archivo)) {
+    return {
+      ok: false,
+      motivo: `basename inválido para firma: "${archivo}". Solo se firman PLAN.md o 0N-PLAN.md de fases.`,
+    };
+  }
+  const lockPath = resolverLockPath(planPath);
+  if (!lockPath) {
+    return {
+      ok: false,
+      motivo: `el PLAN no tiene un directorio .planning ancestro: ${planPath}`,
+    };
+  }
+  const buffer = fs.readFileSync(planPath);
+  const hash = sha256(buffer);
+
+  const lock = {
+    version: LOCK_VERSION,
+    archivo,
+    sha256: hash,
+    firmadoEn: opciones.firmadoEn || new Date().toISOString(),
+    firmadoPor: opciones.firmadoPor || 'swl:aprobar-plan',
+  };
+
+  atomicWriteSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+  return { ok: true, sha256: hash, lockPath, archivo };
+}
+
+/**
+ * Verifica la integridad de un PLAN contra su `.lock`.
+ *
+ * Modos de retorno:
+ *   - `firmado`     : existe lock y el hash coincide  -> ok: true
+ *   - `legacy`      : NO existe lock pero estado:aprobado (gracia D-05) -> ok: true
+ *   - `mutado`      : existe lock y el hash NO coincide -> ok: false
+ *   - `lock-corrupto`: el lock existe pero no es JSON válido -> ok: false
+ *   - `sin-firmar`  : NO existe lock y estado != aprobado -> ok: false
+ *   - `sin-planning`: el PLAN no tiene `.planning` ancestro -> ok: false
+ *   - `no-existe`   : el PLAN no existe en disco -> ok: false
+ *
+ * @param {string} planPath
+ * @returns {{ok: boolean, modo: string, motivo?: string, hashEsperado?: string, hashActual?: string, lockPath?: string}}
+ */
+function verificarPlan(planPath) {
+  if (!fs.existsSync(planPath)) {
+    return { ok: false, modo: 'no-existe', motivo: `PLAN no existe: ${planPath}` };
+  }
+  const lockPath = resolverLockPath(planPath);
+  if (!lockPath) {
+    return {
+      ok: false,
+      modo: 'sin-planning',
+      motivo: `el PLAN no tiene un directorio .planning ancestro: ${planPath}`,
+    };
+  }
+  const buffer = fs.readFileSync(planPath);
+  const hashActual = sha256(buffer);
+
+  if (!fs.existsSync(lockPath)) {
+    // Cláusula de gracia D-05: plan aprobado antes de que existiera el lock.
+    const estado = leerEstado(buffer.toString('utf8'));
+    if (estado === 'aprobado') {
+      return {
+        ok: true,
+        modo: 'legacy',
+        motivo: 'plan aprobado pre-Fase09 (sin lock); ejecutar con advertencia',
+        hashActual,
+        lockPath,
+      };
+    }
+    return {
+      ok: false,
+      modo: 'sin-firmar',
+      motivo: `plan sin aprobar y sin lock (estado: ${estado || 'ausente'})`,
+      hashActual,
+      lockPath,
+    };
+  }
+
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch (err) {
+    return {
+      ok: false,
+      modo: 'lock-corrupto',
+      motivo: `lock malformado en ${lockPath}: ${err.message}`,
+      hashActual,
+      lockPath,
+    };
+  }
+
+  const hashEsperado = lock && typeof lock.sha256 === 'string' ? lock.sha256 : null;
+  if (!hashEsperado) {
+    return {
+      ok: false,
+      modo: 'lock-corrupto',
+      motivo: `lock sin campo sha256 en ${lockPath}`,
+      hashActual,
+      lockPath,
+    };
+  }
+
+  if (hashEsperado === hashActual) {
+    return { ok: true, modo: 'firmado', hashEsperado, hashActual, lockPath };
+  }
+
+  return {
+    ok: false,
+    modo: 'mutado',
+    motivo: 'plan mutado tras aprobación (el hash no coincide con el lock)',
+    hashEsperado,
+    hashActual,
+    lockPath,
+  };
+}
+
+module.exports = {
+  firmarPlan,
+  verificarPlan,
+  resolverLockPath,
+  resolverLocksDir,
+  sha256,
+  leerEstado,
+  LOCK_VERSION,
+};

package/scripts/migrar-fase-dominio.js

@@ -80,7 +80,6 @@ const MAPEO = {
   'revisor-typescript-swl': ['verify', 'quality'],
   'sre-swl': ['release', 'infra'],
   'tdd-qa-swl': ['verify', 'quality'],
-  'ux-disenador-swl': ['plan', 'ux'],
 };
 
 function migrarAgente(nombre) {

package/scripts/verificar-trazabilidad.js

@@ -0,0 +1,292 @@
+#!/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.
+  const re = /^\s*(?:[-*]\s*)?\*{0,2}(REQ-\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;
+    }
+    if (tareaActual && /\*\*Verifica REQ\*\*\s*:/i.test(linea)) {
+      const reqs = linea.match(/REQ-\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}/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})/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 };