@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/longmemeval-runner.js

@@ -1,125 +1,125 @@
-'use strict';
-
-/**
- * longmemeval-runner.js — Adapter que ejecuta queries del benchmark contra
- * `hooks/lib/memory-search` y devuelve métricas.
- *
- * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
- * Adaptado: en lugar de cargar haystack desde el dataset, usa el estado
- * actual del proyecto SWL (APRENDIZAJES.md, sesiones, instintos).
- *
- * El dataset es un JSONL donde cada línea es:
- * {
- *   "question_id":  "q-001",
- *   "question":     "texto libre de la query",
- *   "gold_ids":     ["apr-N", "ses-YYYY-MM-DD-HHMM"],
- *   "category":     "decision" | "patron" | "anti-patron" | "gotcha" | ...,
- *   "status":       "real" | "placeholder"
- * }
- *
- * @module scripts/lib/longmemeval-runner
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const memorySearch     = require('../../hooks/lib/memory-search');
-const benchmarkMetrics = require('./benchmark-metrics');
-
-// ── parser de dataset ─────────────────────────────────────────────────────────
-
-/**
- * Parsea un archivo JSONL del dataset.
- * @param {string} ruta
- * @returns {object[]}
- */
-function leerDataset(ruta) {
-  if (!fs.existsSync(ruta)) {
-    throw new Error(`Dataset no encontrado: ${ruta}`);
-  }
-  const contenido = fs.readFileSync(ruta, 'utf8');
-  const entries = [];
-  let lineNum = 0;
-  for (const linea of contenido.split('\n')) {
-    lineNum++;
-    if (!linea.trim()) continue;
-    if (linea.trim().startsWith('//')) continue; // comentarios
-    try {
-      entries.push(JSON.parse(linea));
-    } catch (err) {
-      throw new Error(`JSONL malformado en línea ${lineNum}: ${err.message}`);
-    }
-  }
-  return entries;
-}
-
-// ── ejecución de query individual ─────────────────────────────────────────────
-
-/**
- * Ejecuta una query del benchmark contra memoria SWL y compara con gold.
- *
- * @param {string} baseDir - Raíz del proyecto.
- * @param {object} entry - Una línea del dataset.
- * @param {object} [opts]
- * @param {number} [opts.limit=20] - Top-k a recuperar.
- * @returns {object} Métricas + ids retrieved + entry original.
- */
-function ejecutarEntry(baseDir, entry, opts = {}) {
-  const limit = opts.limit || 20;
-  const inicio = Date.now();
-  const resultados = memorySearch.search(baseDir, entry.question, { limit });
-  const latencyMs = Date.now() - inicio;
-
-  const retrievedIds = resultados.map(r => r.id);
-  const goldIds = Array.isArray(entry.gold_ids) ? entry.gold_ids : [];
-  const metricas = benchmarkMetrics.calcularMetricas(retrievedIds, goldIds);
-
-  return {
-    question_id: entry.question_id || 'unknown',
-    question: entry.question,
-    category: entry.category || null,
-    status: entry.status || 'unknown',
-    retrievedIds,
-    goldIds,
-    metricas,
-    latencyMs,
-  };
-}
-
-/**
- * Ejecuta el dataset completo y devuelve resultados + métricas agregadas.
- *
- * @param {string} baseDir
- * @param {string} datasetPath
- * @param {object} [opts]
- * @returns {{ entries: object[], promedio: object, dataset: object }}
- */
-function ejecutarDataset(baseDir, datasetPath, opts = {}) {
-  const entries = leerDataset(datasetPath);
-  const resultados = entries.map(e => ejecutarEntry(baseDir, e, opts));
-  const promedio = benchmarkMetrics.promediar(resultados.map(r => r.metricas));
-
-  // Estadísticas del dataset
-  const placeholderCount = entries.filter(e => e.status === 'placeholder').length;
-  const realCount = entries.filter(e => e.status === 'real').length;
-  const datasetMeta = {
-    total: entries.length,
-    real: realCount,
-    placeholder: placeholderCount,
-    significativo: realCount >= 30,
-  };
-
-  return {
-    entries: resultados,
-    promedio,
-    dataset: datasetMeta,
-  };
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  leerDataset,
-  ejecutarEntry,
-  ejecutarDataset,
-};
+'use strict';
+
+/**
+ * longmemeval-runner.js — Adapter que ejecuta queries del benchmark contra
+ * `hooks/lib/memory-search` y devuelve métricas.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Adaptado: en lugar de cargar haystack desde el dataset, usa el estado
+ * actual del proyecto SWL (APRENDIZAJES.md, sesiones, instintos).
+ *
+ * El dataset es un JSONL donde cada línea es:
+ * {
+ *   "question_id":  "q-001",
+ *   "question":     "texto libre de la query",
+ *   "gold_ids":     ["apr-N", "ses-YYYY-MM-DD-HHMM"],
+ *   "category":     "decision" | "patron" | "anti-patron" | "gotcha" | ...,
+ *   "status":       "real" | "placeholder"
+ * }
+ *
+ * @module scripts/lib/longmemeval-runner
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const memorySearch     = require('../../hooks/lib/memory-search');
+const benchmarkMetrics = require('./benchmark-metrics');
+
+// ── parser de dataset ─────────────────────────────────────────────────────────
+
+/**
+ * Parsea un archivo JSONL del dataset.
+ * @param {string} ruta
+ * @returns {object[]}
+ */
+function leerDataset(ruta) {
+  if (!fs.existsSync(ruta)) {
+    throw new Error(`Dataset no encontrado: ${ruta}`);
+  }
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  const entries = [];
+  let lineNum = 0;
+  for (const linea of contenido.split('\n')) {
+    lineNum++;
+    if (!linea.trim()) continue;
+    if (linea.trim().startsWith('//')) continue; // comentarios
+    try {
+      entries.push(JSON.parse(linea));
+    } catch (err) {
+      throw new Error(`JSONL malformado en línea ${lineNum}: ${err.message}`);
+    }
+  }
+  return entries;
+}
+
+// ── ejecución de query individual ─────────────────────────────────────────────
+
+/**
+ * Ejecuta una query del benchmark contra memoria SWL y compara con gold.
+ *
+ * @param {string} baseDir - Raíz del proyecto.
+ * @param {object} entry - Una línea del dataset.
+ * @param {object} [opts]
+ * @param {number} [opts.limit=20] - Top-k a recuperar.
+ * @returns {object} Métricas + ids retrieved + entry original.
+ */
+function ejecutarEntry(baseDir, entry, opts = {}) {
+  const limit = opts.limit || 20;
+  const inicio = Date.now();
+  const resultados = memorySearch.search(baseDir, entry.question, { limit });
+  const latencyMs = Date.now() - inicio;
+
+  const retrievedIds = resultados.map(r => r.id);
+  const goldIds = Array.isArray(entry.gold_ids) ? entry.gold_ids : [];
+  const metricas = benchmarkMetrics.calcularMetricas(retrievedIds, goldIds);
+
+  return {
+    question_id: entry.question_id || 'unknown',
+    question: entry.question,
+    category: entry.category || null,
+    status: entry.status || 'unknown',
+    retrievedIds,
+    goldIds,
+    metricas,
+    latencyMs,
+  };
+}
+
+/**
+ * Ejecuta el dataset completo y devuelve resultados + métricas agregadas.
+ *
+ * @param {string} baseDir
+ * @param {string} datasetPath
+ * @param {object} [opts]
+ * @returns {{ entries: object[], promedio: object, dataset: object }}
+ */
+function ejecutarDataset(baseDir, datasetPath, opts = {}) {
+  const entries = leerDataset(datasetPath);
+  const resultados = entries.map(e => ejecutarEntry(baseDir, e, opts));
+  const promedio = benchmarkMetrics.promediar(resultados.map(r => r.metricas));
+
+  // Estadísticas del dataset
+  const placeholderCount = entries.filter(e => e.status === 'placeholder').length;
+  const realCount = entries.filter(e => e.status === 'real').length;
+  const datasetMeta = {
+    total: entries.length,
+    real: realCount,
+    placeholder: placeholderCount,
+    significativo: realCount >= 30,
+  };
+
+  return {
+    entries: resultados,
+    promedio,
+    dataset: datasetMeta,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  leerDataset,
+  ejecutarEntry,
+  ejecutarDataset,
+};

package/scripts/lib/metricas-dora.js

@@ -1,204 +1,204 @@
-'use strict';
-
-/**
- * metricas-dora.js
- *
- * Compone las 4 métricas DORA del proyecto destino y las clasifica en
- * elite/high/medium/low según los umbrales del DORA Report 2023:
- *   - deployment frequency + lead time desde git (siempre, git-metricas.js).
- *   - change failure rate + MTTR desde gh (degrada si ausente, ci-reader.js).
- *
- * Persiste el informe en `.planning/evolution/metricas-dora.json` (runtime).
- * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const gitMetricas = require('./git-metricas');
-const ciReader = require('./ci-reader');
-
-let atomicWriteJSON;
-try {
-  ({ atomicWriteJSON } = require('../../hooks/lib/atomic-write'));
-} catch (err) {
-  if (err.code !== 'MODULE_NOT_FOUND') throw err;
-  atomicWriteJSON = (p, obj) => {
-    const dir = path.dirname(p);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
-  };
-}
-
-const STORAGE_REL = path.join('.planning', 'evolution', 'metricas-dora.json');
-
-/**
- * Umbrales DORA Report 2023 (Accelerate State of DevOps). Boundaries expresados
- * en las unidades internas de cada métrica. Ajustar aquí si el reporte cambia.
- *
- * - deploymentFrequency (deploys/semana, mayor es mejor):
- *   elite ≥1/día (7/sem) · high ≥1/mes (0.23/sem) · medium ≥1/semestre (0.038/sem) · low <semestral.
- * - leadTimeHoras (commit→tag, menor es mejor): elite <1día · high <1sem · medium <1mes · low ≥1mes.
- * - changeFailureRate (0..1, menor es mejor): elite ≤0.15 · high ≤0.30 · medium ≤0.45 · low >0.45.
- * - mttrHoras (menor es mejor): elite <1h · high <1día · medium <1sem · low ≥1sem.
- */
-const UMBRALES_DORA_2023 = {
-  deploymentFrequency: { elite: 7, high: 0.23, medium: 0.038 }, // deploys/semana, mayor mejor
-  leadTimeHoras: { elite: 24, high: 168, medium: 730 }, // menor mejor
-  changeFailureRate: { elite: 0.15, high: 0.3, medium: 0.45 }, // menor mejor
-  mttrHoras: { elite: 1, high: 24, medium: 168 }, // menor mejor
-};
-
-const NIVELES = ['elite', 'high', 'medium', 'low'];
-
-/**
- * Clasifica un valor de una métrica en elite/high/medium/low.
- * @param {string} metrica - clave de UMBRALES_DORA_2023.
- * @param {number|null|undefined} valor
- * @returns {'elite'|'high'|'medium'|'low'|'sin-datos'}
- */
-function clasificar(metrica, valor) {
-  const u = UMBRALES_DORA_2023[metrica];
-  if (!u || valor === null || valor === undefined || !Number.isFinite(valor)) return 'sin-datos';
-
-  if (metrica === 'deploymentFrequency') {
-    // mayor es mejor
-    if (valor >= u.elite) return 'elite';
-    if (valor >= u.high) return 'high';
-    if (valor >= u.medium) return 'medium';
-    return 'low';
-  }
-  // menor es mejor (leadTime, cfr, mttr)
-  if (valor < u.elite) return 'elite';
-  if (valor < u.high) return 'high';
-  if (valor < u.medium) return 'medium';
-  return 'low';
-}
-
-/**
- * Calcula las 4 métricas DORA del proyecto en baseDir.
- * @returns objeto serializable con generado, ventana_dias y las 4 métricas.
- */
-function calcularDora(baseDir = process.cwd(), opts = {}) {
-  const { ventanaDias = 30, hoy = new Date(), ejecutorGh } = opts;
-
-  // Git (siempre)
-  const df = gitMetricas.deploymentFrequency(baseDir, { ventanaDias, hoy });
-  const lt = gitMetricas.leadTimeForChanges(baseDir, { ventanaDias, hoy });
-
-  // CI (degrada): una sola llamada a gh. Si no está disponible, NO se re-intenta
-  // — se propaga la razón directamente (evita 3 invocaciones del mismo fallo).
-  const runsBase = ciReader.obtenerRuns({ ejecutorGh, rama: 'main' });
-  const cfr = runsBase.disponible
-    ? ciReader.changeFailureRate({ ventanaDias, hoy, runs: runsBase.runs })
-    : { disponible: false, razon: runsBase.razon };
-  const mttr = runsBase.disponible
-    ? ciReader.meanTimeToRestore({ ventanaDias, hoy, runs: runsBase.runs })
-    : { disponible: false, razon: runsBase.razon };
-
-  const deploymentFrequency = df.disponible
-    ? {
-        disponible: true,
-        valor: df.sinDatos ? null : df.deploysPorSemana,
-        unidad: 'deploys/semana',
-        clasificacion: df.sinDatos ? 'sin-datos' : clasificar('deploymentFrequency', df.deploysPorSemana),
-        sinDatos: !!df.sinDatos,
-      }
-    : { disponible: false, razon: df.razon };
-
-  const leadTime = lt.disponible
-    ? {
-        disponible: true,
-        p50Horas: lt.sinDatos ? null : lt.p50Horas,
-        p95Horas: lt.sinDatos ? null : lt.p95Horas,
-        clasificacion: lt.sinDatos ? 'sin-datos' : clasificar('leadTimeHoras', lt.p50Horas),
-        sinDatos: !!lt.sinDatos,
-      }
-    : { disponible: false, razon: lt.razon };
-
-  const changeFailureRate = cfr.disponible
-    ? {
-        disponible: true,
-        valor: cfr.sinDatos ? null : cfr.cfr,
-        clasificacion: cfr.sinDatos ? 'sin-datos' : clasificar('changeFailureRate', cfr.cfr),
-        sinDatos: !!cfr.sinDatos,
-        totalRuns: cfr.totalRuns,
-        fallidos: cfr.fallidos,
-      }
-    : { disponible: false, razon: cfr.razon };
-
-  const mttrOut = mttr.disponible
-    ? {
-        disponible: true,
-        mttrHoras: mttr.sinDatos ? null : mttr.mttrHoras,
-        clasificacion: mttr.sinDatos ? 'sin-datos' : clasificar('mttrHoras', mttr.mttrHoras),
-        sinDatos: !!mttr.sinDatos,
-        recuperaciones: mttr.recuperaciones,
-      }
-    : { disponible: false, razon: mttr.razon };
-
-  return {
-    generado: hoy.toISOString(),
-    ventana_dias: ventanaDias,
-    deploymentFrequency,
-    leadTime,
-    changeFailureRate,
-    mttr: mttrOut,
-  };
-}
-
-/**
- * Persiste el informe DORA en `<baseDir>/.planning/evolution/metricas-dora.json`.
- * `baseDir` se trata como ruta CONFIABLE del invocador (CLI local / cwd); NUNCA
- * debe propagarse desde input web/HTTP/PR. Aun así se valida contención bajo
- * baseDir para evitar write-anywhere si el path subiera de nivel (H-01).
- */
-function persistir(baseDir, dora) {
-  const base = path.resolve(baseDir);
-  const destino = path.resolve(base, STORAGE_REL);
-  if (destino !== base && !destino.startsWith(base + path.sep)) {
-    throw new Error('destino de métricas DORA fuera de baseDir');
-  }
-  atomicWriteJSON(destino, dora);
-  return destino;
-}
-
-module.exports = {
-  clasificar,
-  calcularDora,
-  persistir,
-  UMBRALES_DORA_2023,
-  NIVELES,
-  STORAGE_REL,
-};
-
-// Entrypoint CLI: node scripts/lib/metricas-dora.js [--json] [--dias=N] [baseDir]
-if (!require.main || require.main === module) {
-  const args = process.argv.slice(2);
-  const json = args.includes('--json');
-  const diasArg = args.find((a) => a.startsWith('--dias='));
-  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
-  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
-
-  const dora = calcularDora(baseDir, { ventanaDias });
-  try {
-    persistir(baseDir, dora);
-  } catch {
-    /* persistencia best-effort: no romper el informe si el disco falla */
-  }
-
-  if (json) {
-    process.stdout.write(JSON.stringify(dora, null, 2) + '\n');
-  } else {
-    const fmt = (txt) => process.stdout.write(`${txt}\n`);
-    const df = dora.deploymentFrequency;
-    const lt = dora.leadTime;
-    const cfr = dora.changeFailureRate;
-    const mt = dora.mttr;
-    fmt(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : `${df.valor.toFixed(2)}/sem [${df.clasificacion}]`) : 'no disponible'}`);
-    fmt(`Lead time (p50): ${lt.disponible ? (lt.sinDatos ? 'sin datos' : `${lt.p50Horas.toFixed(1)}h [${lt.clasificacion}]`) : 'no disponible'}`);
-    fmt(`Change failure rate: ${cfr.disponible ? (cfr.sinDatos ? 'sin datos' : `${(cfr.valor * 100).toFixed(1)}% [${cfr.clasificacion}]`) : 'no disponible (gh ausente)'}`);
-    fmt(`MTTR: ${mt.disponible ? (mt.sinDatos ? 'sin datos' : `${mt.mttrHoras.toFixed(1)}h [${mt.clasificacion}]`) : 'no disponible (gh ausente)'}`);
-  }
-  process.exit(0);
-}
+'use strict';
+
+/**
+ * metricas-dora.js
+ *
+ * Compone las 4 métricas DORA del proyecto destino y las clasifica en
+ * elite/high/medium/low según los umbrales del DORA Report 2023:
+ *   - deployment frequency + lead time desde git (siempre, git-metricas.js).
+ *   - change failure rate + MTTR desde gh (degrada si ausente, ci-reader.js).
+ *
+ * Persiste el informe en `.planning/evolution/metricas-dora.json` (runtime).
+ * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const gitMetricas = require('./git-metricas');
+const ciReader = require('./ci-reader');
+
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('../../hooks/lib/atomic-write'));
+} catch (err) {
+  if (err.code !== 'MODULE_NOT_FOUND') throw err;
+  atomicWriteJSON = (p, obj) => {
+    const dir = path.dirname(p);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+  };
+}
+
+const STORAGE_REL = path.join('.planning', 'evolution', 'metricas-dora.json');
+
+/**
+ * Umbrales DORA Report 2023 (Accelerate State of DevOps). Boundaries expresados
+ * en las unidades internas de cada métrica. Ajustar aquí si el reporte cambia.
+ *
+ * - deploymentFrequency (deploys/semana, mayor es mejor):
+ *   elite ≥1/día (7/sem) · high ≥1/mes (0.23/sem) · medium ≥1/semestre (0.038/sem) · low <semestral.
+ * - leadTimeHoras (commit→tag, menor es mejor): elite <1día · high <1sem · medium <1mes · low ≥1mes.
+ * - changeFailureRate (0..1, menor es mejor): elite ≤0.15 · high ≤0.30 · medium ≤0.45 · low >0.45.
+ * - mttrHoras (menor es mejor): elite <1h · high <1día · medium <1sem · low ≥1sem.
+ */
+const UMBRALES_DORA_2023 = {
+  deploymentFrequency: { elite: 7, high: 0.23, medium: 0.038 }, // deploys/semana, mayor mejor
+  leadTimeHoras: { elite: 24, high: 168, medium: 730 }, // menor mejor
+  changeFailureRate: { elite: 0.15, high: 0.3, medium: 0.45 }, // menor mejor
+  mttrHoras: { elite: 1, high: 24, medium: 168 }, // menor mejor
+};
+
+const NIVELES = ['elite', 'high', 'medium', 'low'];
+
+/**
+ * Clasifica un valor de una métrica en elite/high/medium/low.
+ * @param {string} metrica - clave de UMBRALES_DORA_2023.
+ * @param {number|null|undefined} valor
+ * @returns {'elite'|'high'|'medium'|'low'|'sin-datos'}
+ */
+function clasificar(metrica, valor) {
+  const u = UMBRALES_DORA_2023[metrica];
+  if (!u || valor === null || valor === undefined || !Number.isFinite(valor)) return 'sin-datos';
+
+  if (metrica === 'deploymentFrequency') {
+    // mayor es mejor
+    if (valor >= u.elite) return 'elite';
+    if (valor >= u.high) return 'high';
+    if (valor >= u.medium) return 'medium';
+    return 'low';
+  }
+  // menor es mejor (leadTime, cfr, mttr)
+  if (valor < u.elite) return 'elite';
+  if (valor < u.high) return 'high';
+  if (valor < u.medium) return 'medium';
+  return 'low';
+}
+
+/**
+ * Calcula las 4 métricas DORA del proyecto en baseDir.
+ * @returns objeto serializable con generado, ventana_dias y las 4 métricas.
+ */
+function calcularDora(baseDir = process.cwd(), opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), ejecutorGh } = opts;
+
+  // Git (siempre)
+  const df = gitMetricas.deploymentFrequency(baseDir, { ventanaDias, hoy });
+  const lt = gitMetricas.leadTimeForChanges(baseDir, { ventanaDias, hoy });
+
+  // CI (degrada): una sola llamada a gh. Si no está disponible, NO se re-intenta
+  // — se propaga la razón directamente (evita 3 invocaciones del mismo fallo).
+  const runsBase = ciReader.obtenerRuns({ ejecutorGh, rama: 'main' });
+  const cfr = runsBase.disponible
+    ? ciReader.changeFailureRate({ ventanaDias, hoy, runs: runsBase.runs })
+    : { disponible: false, razon: runsBase.razon };
+  const mttr = runsBase.disponible
+    ? ciReader.meanTimeToRestore({ ventanaDias, hoy, runs: runsBase.runs })
+    : { disponible: false, razon: runsBase.razon };
+
+  const deploymentFrequency = df.disponible
+    ? {
+        disponible: true,
+        valor: df.sinDatos ? null : df.deploysPorSemana,
+        unidad: 'deploys/semana',
+        clasificacion: df.sinDatos ? 'sin-datos' : clasificar('deploymentFrequency', df.deploysPorSemana),
+        sinDatos: !!df.sinDatos,
+      }
+    : { disponible: false, razon: df.razon };
+
+  const leadTime = lt.disponible
+    ? {
+        disponible: true,
+        p50Horas: lt.sinDatos ? null : lt.p50Horas,
+        p95Horas: lt.sinDatos ? null : lt.p95Horas,
+        clasificacion: lt.sinDatos ? 'sin-datos' : clasificar('leadTimeHoras', lt.p50Horas),
+        sinDatos: !!lt.sinDatos,
+      }
+    : { disponible: false, razon: lt.razon };
+
+  const changeFailureRate = cfr.disponible
+    ? {
+        disponible: true,
+        valor: cfr.sinDatos ? null : cfr.cfr,
+        clasificacion: cfr.sinDatos ? 'sin-datos' : clasificar('changeFailureRate', cfr.cfr),
+        sinDatos: !!cfr.sinDatos,
+        totalRuns: cfr.totalRuns,
+        fallidos: cfr.fallidos,
+      }
+    : { disponible: false, razon: cfr.razon };
+
+  const mttrOut = mttr.disponible
+    ? {
+        disponible: true,
+        mttrHoras: mttr.sinDatos ? null : mttr.mttrHoras,
+        clasificacion: mttr.sinDatos ? 'sin-datos' : clasificar('mttrHoras', mttr.mttrHoras),
+        sinDatos: !!mttr.sinDatos,
+        recuperaciones: mttr.recuperaciones,
+      }
+    : { disponible: false, razon: mttr.razon };
+
+  return {
+    generado: hoy.toISOString(),
+    ventana_dias: ventanaDias,
+    deploymentFrequency,
+    leadTime,
+    changeFailureRate,
+    mttr: mttrOut,
+  };
+}
+
+/**
+ * Persiste el informe DORA en `<baseDir>/.planning/evolution/metricas-dora.json`.
+ * `baseDir` se trata como ruta CONFIABLE del invocador (CLI local / cwd); NUNCA
+ * debe propagarse desde input web/HTTP/PR. Aun así se valida contención bajo
+ * baseDir para evitar write-anywhere si el path subiera de nivel (H-01).
+ */
+function persistir(baseDir, dora) {
+  const base = path.resolve(baseDir);
+  const destino = path.resolve(base, STORAGE_REL);
+  if (destino !== base && !destino.startsWith(base + path.sep)) {
+    throw new Error('destino de métricas DORA fuera de baseDir');
+  }
+  atomicWriteJSON(destino, dora);
+  return destino;
+}
+
+module.exports = {
+  clasificar,
+  calcularDora,
+  persistir,
+  UMBRALES_DORA_2023,
+  NIVELES,
+  STORAGE_REL,
+};
+
+// Entrypoint CLI: node scripts/lib/metricas-dora.js [--json] [--dias=N] [baseDir]
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const diasArg = args.find((a) => a.startsWith('--dias='));
+  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
+  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
+
+  const dora = calcularDora(baseDir, { ventanaDias });
+  try {
+    persistir(baseDir, dora);
+  } catch {
+    /* persistencia best-effort: no romper el informe si el disco falla */
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(dora, null, 2) + '\n');
+  } else {
+    const fmt = (txt) => process.stdout.write(`${txt}\n`);
+    const df = dora.deploymentFrequency;
+    const lt = dora.leadTime;
+    const cfr = dora.changeFailureRate;
+    const mt = dora.mttr;
+    fmt(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : `${df.valor.toFixed(2)}/sem [${df.clasificacion}]`) : 'no disponible'}`);
+    fmt(`Lead time (p50): ${lt.disponible ? (lt.sinDatos ? 'sin datos' : `${lt.p50Horas.toFixed(1)}h [${lt.clasificacion}]`) : 'no disponible'}`);
+    fmt(`Change failure rate: ${cfr.disponible ? (cfr.sinDatos ? 'sin datos' : `${(cfr.valor * 100).toFixed(1)}% [${cfr.clasificacion}]`) : 'no disponible (gh ausente)'}`);
+    fmt(`MTTR: ${mt.disponible ? (mt.sinDatos ? 'sin datos' : `${mt.mttrHoras.toFixed(1)}h [${mt.clasificacion}]`) : 'no disponible (gh ausente)'}`);
+  }
+  process.exit(0);
+}