@saulwade/swl-ses 2.6.0 → 2.6.1

package/scripts/cli/ciclo-fase-b.js

@@ -1,102 +1,102 @@
-'use strict';
-
-/**
- * Subcomando `swl-ses ciclo-fase-b [status] [--dry-run]` — CLI headless de la
- * Fase B del ciclo autónomo (Fase 22, T-07, ADR-0042 gate G-B, REQ-22-07).
- *
- * Espeja el patrón de `scripts/cli/ciclo-autonomo.js` (contrato del bin: cada
- * subcomando exporta UNA función(opciones) sin efectos al require).
- *
- *   (nada) | --dry-run → corre `runner-fase-b.correrFaseB` con `dryRun:true`
- *     SIEMPRE, se pase o no el flag. En Fase 22 el runner NUNCA invoca LLM ni
- *     gasta bajo ninguna combinación de argumentos — el modo real
- *     (`dryRun:false` + `invocador` cableado) llega en Fase 24; hasta
- *     entonces `--dry-run` es un no-op explícito frente al default.
- *   status → reporta `fase_b_habilitada`, `last_run_fase_b`, candidatos
- *     pendientes (conteo tolerante de `evolution/candidatos-fase-b.jsonl` —
- *     NUNCA `candidatos.detectar`, que tiene efecto de escritura; `status`
- *     jamás muta disco) y el estado de presupuesto (`gasto_mes`,
- *     `presupuesto_usd_mes`, `pausado_por_presupuesto`) vía
- *     `presupuesto.estado`.
- *
- * Uso: swl-ses ciclo-fase-b [status] [--dry-run]
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const { correrFaseB } = require('../lib/ciclo-autonomo/runner-fase-b');
-const config = require('../lib/ciclo-autonomo/config');
-const presupuesto = require('../lib/ciclo-autonomo/presupuesto');
-
-const RUTA_CANDIDATOS_RELATIVA = path.join('.planning', 'evolution', 'candidatos-fase-b.jsonl');
-
-/**
- * Conteo tolerante de líneas JSON válidas en `candidatos-fase-b.jsonl`.
- * `status` es de solo lectura: nunca invoca `candidatos.detectar` (que
- * persiste candidatos nuevos) — solo cuenta lo que YA quedó registrado por
- * una corrida previa de la Fase A o del runner.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {number}
- */
-function contarCandidatosPendientes(baseDir) {
-  let crudo;
-  try {
-    crudo = fs.readFileSync(path.join(baseDir, RUTA_CANDIDATOS_RELATIVA), 'utf8');
-  } catch (_) {
-    return 0;
-  }
-  return crudo.split(/\r\n|\n/)
-    .filter((linea) => linea.trim() !== '')
-    .filter((linea) => {
-      try {
-        JSON.parse(linea);
-        return true;
-      } catch (_) {
-        return false;
-      }
-    }).length;
-}
-
-function cicloFaseB(opciones = {}) {
-  const accion = (opciones._args || [])[0];
-  const baseDir = opciones.dir || process.cwd();
-
-  if (accion === 'status') {
-    const cfg = config.leerConfig(baseDir);
-    const presu = presupuesto.estado(baseDir);
-    const estado = {
-      fase_b_habilitada: config.estaFaseBHabilitada(baseDir),
-      last_run_fase_b: cfg.last_run_fase_b,
-      candidatos_pendientes: contarCandidatosPendientes(baseDir),
-      gasto_mes: presu.gasto_mes,
-      presupuesto_usd_mes: presu.tope,
-      pausado_por_presupuesto: presu.pausado_por_presupuesto,
-    };
-    console.log(`[ciclo-fase-b] fase_b_habilitada: ${estado.fase_b_habilitada}`);
-    console.log(`[ciclo-fase-b] last_run_fase_b: ${estado.last_run_fase_b || 'nunca'}`);
-    console.log(`[ciclo-fase-b] candidatos_pendientes: ${estado.candidatos_pendientes}`);
-    console.log(`[ciclo-fase-b] gasto_mes: $${estado.gasto_mes} / $${estado.presupuesto_usd_mes} · pausado_por_presupuesto: ${estado.pausado_por_presupuesto}`);
-    return estado;
-  }
-
-  if (accion !== undefined && accion !== '--dry-run') {
-    console.error(`[ciclo-fase-b] acción desconocida: "${accion}". Uso: swl-ses ciclo-fase-b [status] [--dry-run]`);
-    process.exitCode = 1;
-    return null;
-  }
-
-  // Fase 22: dryRun forzado a true sin importar el flag — el runner valida
-  // toda la tubería (lock, catch-up, guard, credencial, presupuesto) y
-  // registra la corrida SIN invocar LLM. El modo real llega en Fase 24.
-  const resultado = correrFaseB(baseDir, { dryRun: true });
-  if (!resultado.ejecutado) {
-    console.log(`[ciclo-fase-b] sin corrida: ${resultado.razon}`);
-  } else {
-    console.log(`[ciclo-fase-b] corrida dry-run completada — candidatos: ${resultado.candidatos}`);
-  }
-  return resultado;
-}
-
-module.exports = cicloFaseB;
+'use strict';
+
+/**
+ * Subcomando `swl-ses ciclo-fase-b [status] [--dry-run]` — CLI headless de la
+ * Fase B del ciclo autónomo (Fase 22, T-07, ADR-0042 gate G-B, REQ-22-07).
+ *
+ * Espeja el patrón de `scripts/cli/ciclo-autonomo.js` (contrato del bin: cada
+ * subcomando exporta UNA función(opciones) sin efectos al require).
+ *
+ *   (nada) | --dry-run → corre `runner-fase-b.correrFaseB` con `dryRun:true`
+ *     SIEMPRE, se pase o no el flag. En Fase 22 el runner NUNCA invoca LLM ni
+ *     gasta bajo ninguna combinación de argumentos — el modo real
+ *     (`dryRun:false` + `invocador` cableado) llega en Fase 24; hasta
+ *     entonces `--dry-run` es un no-op explícito frente al default.
+ *   status → reporta `fase_b_habilitada`, `last_run_fase_b`, candidatos
+ *     pendientes (conteo tolerante de `evolution/candidatos-fase-b.jsonl` —
+ *     NUNCA `candidatos.detectar`, que tiene efecto de escritura; `status`
+ *     jamás muta disco) y el estado de presupuesto (`gasto_mes`,
+ *     `presupuesto_usd_mes`, `pausado_por_presupuesto`) vía
+ *     `presupuesto.estado`.
+ *
+ * Uso: swl-ses ciclo-fase-b [status] [--dry-run]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { correrFaseB } = require('../lib/ciclo-autonomo/runner-fase-b');
+const config = require('../lib/ciclo-autonomo/config');
+const presupuesto = require('../lib/ciclo-autonomo/presupuesto');
+
+const RUTA_CANDIDATOS_RELATIVA = path.join('.planning', 'evolution', 'candidatos-fase-b.jsonl');
+
+/**
+ * Conteo tolerante de líneas JSON válidas en `candidatos-fase-b.jsonl`.
+ * `status` es de solo lectura: nunca invoca `candidatos.detectar` (que
+ * persiste candidatos nuevos) — solo cuenta lo que YA quedó registrado por
+ * una corrida previa de la Fase A o del runner.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {number}
+ */
+function contarCandidatosPendientes(baseDir) {
+  let crudo;
+  try {
+    crudo = fs.readFileSync(path.join(baseDir, RUTA_CANDIDATOS_RELATIVA), 'utf8');
+  } catch (_) {
+    return 0;
+  }
+  return crudo.split(/\r\n|\n/)
+    .filter((linea) => linea.trim() !== '')
+    .filter((linea) => {
+      try {
+        JSON.parse(linea);
+        return true;
+      } catch (_) {
+        return false;
+      }
+    }).length;
+}
+
+function cicloFaseB(opciones = {}) {
+  const accion = (opciones._args || [])[0];
+  const baseDir = opciones.dir || process.cwd();
+
+  if (accion === 'status') {
+    const cfg = config.leerConfig(baseDir);
+    const presu = presupuesto.estado(baseDir);
+    const estado = {
+      fase_b_habilitada: config.estaFaseBHabilitada(baseDir),
+      last_run_fase_b: cfg.last_run_fase_b,
+      candidatos_pendientes: contarCandidatosPendientes(baseDir),
+      gasto_mes: presu.gasto_mes,
+      presupuesto_usd_mes: presu.tope,
+      pausado_por_presupuesto: presu.pausado_por_presupuesto,
+    };
+    console.log(`[ciclo-fase-b] fase_b_habilitada: ${estado.fase_b_habilitada}`);
+    console.log(`[ciclo-fase-b] last_run_fase_b: ${estado.last_run_fase_b || 'nunca'}`);
+    console.log(`[ciclo-fase-b] candidatos_pendientes: ${estado.candidatos_pendientes}`);
+    console.log(`[ciclo-fase-b] gasto_mes: $${estado.gasto_mes} / $${estado.presupuesto_usd_mes} · pausado_por_presupuesto: ${estado.pausado_por_presupuesto}`);
+    return estado;
+  }
+
+  if (accion !== undefined && accion !== '--dry-run') {
+    console.error(`[ciclo-fase-b] acción desconocida: "${accion}". Uso: swl-ses ciclo-fase-b [status] [--dry-run]`);
+    process.exitCode = 1;
+    return null;
+  }
+
+  // Fase 22: dryRun forzado a true sin importar el flag — el runner valida
+  // toda la tubería (lock, catch-up, guard, credencial, presupuesto) y
+  // registra la corrida SIN invocar LLM. El modo real llega en Fase 24.
+  const resultado = correrFaseB(baseDir, { dryRun: true });
+  if (!resultado.ejecutado) {
+    console.log(`[ciclo-fase-b] sin corrida: ${resultado.razon}`);
+  } else {
+    console.log(`[ciclo-fase-b] corrida dry-run completada — candidatos: ${resultado.candidatos}`);
+  }
+  return resultado;
+}
+
+module.exports = cicloFaseB;

package/scripts/cli/guardrail-metrics.js

@@ -1,39 +1,39 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses guardrail-metrics` — métricas y diagnóstico de los
- * guardrails de la sesión (bridge en tmpdir por sessionId). Reemplaza el
- * `node -e "require('./hooks/lib/guardrail-metrics')..."` relativo al
- * proyecto que swl-dashboard instruía — roto downstream (ver
- * docs/invocacion-cli-cross-scope.md).
- *
- * Uso: swl-ses guardrail-metrics [--session=ID] [--json]
- *   --session  default: env CLAUDE_SESSION_ID o "default"
- *   --json     imprime {metricas, advertencias} crudo
- */
-
-const { getMetrics, formatearResumen, diagnosticar } = require('../../hooks/lib/guardrail-metrics');
-
-function guardrailMetrics(opciones = {}) {
-  const sessionId = (opciones.session != null && opciones.session !== true)
-    ? String(opciones.session)
-    : (process.env.CLAUDE_SESSION_ID || 'default');
-
-  const metricas = getMetrics(sessionId);
-  const advertencias = diagnosticar(metricas);
-
-  if (opciones.json) {
-    console.log(JSON.stringify({ metricas, advertencias }, null, 2));
-    return;
-  }
-
-  console.log(formatearResumen(metricas));
-  if (advertencias.length > 0) {
-    console.log('\n⚠ Diagnóstico:');
-    for (const a of advertencias) console.log('  - ' + a);
-  } else {
-    console.log('\n✓ Guardrails sin anomalías detectadas.');
-  }
-}
-
-module.exports = guardrailMetrics;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses guardrail-metrics` — métricas y diagnóstico de los
+ * guardrails de la sesión (bridge en tmpdir por sessionId). Reemplaza el
+ * `node -e "require('./hooks/lib/guardrail-metrics')..."` relativo al
+ * proyecto que swl-dashboard instruía — roto downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses guardrail-metrics [--session=ID] [--json]
+ *   --session  default: env CLAUDE_SESSION_ID o "default"
+ *   --json     imprime {metricas, advertencias} crudo
+ */
+
+const { getMetrics, formatearResumen, diagnosticar } = require('../../hooks/lib/guardrail-metrics');
+
+function guardrailMetrics(opciones = {}) {
+  const sessionId = (opciones.session != null && opciones.session !== true)
+    ? String(opciones.session)
+    : (process.env.CLAUDE_SESSION_ID || 'default');
+
+  const metricas = getMetrics(sessionId);
+  const advertencias = diagnosticar(metricas);
+
+  if (opciones.json) {
+    console.log(JSON.stringify({ metricas, advertencias }, null, 2));
+    return;
+  }
+
+  console.log(formatearResumen(metricas));
+  if (advertencias.length > 0) {
+    console.log('\n⚠ Diagnóstico:');
+    for (const a of advertencias) console.log('  - ' + a);
+  } else {
+    console.log('\n✓ Guardrails sin anomalías detectadas.');
+  }
+}
+
+module.exports = guardrailMetrics;

package/scripts/cli/memoria-search.js

@@ -1,69 +1,69 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses memoria-search <op>` — búsqueda en la memoria del
- * proyecto (.planning/sessions/, APRENDIZAJES.md, diary). Reemplaza los
- * `require('./hooks/lib/memory-search')` relativos al proyecto que
- * memoria-busqueda y benchmark-memoria instruían — rotos downstream (ver
- * docs/invocacion-cli-cross-scope.md).
- *
- * Ops:
- *   search   --query="..." [--limit=N] [--tipo=aprendizaje|sesion|instinto]
- *            [--desde=YYYY-MM-DD] [--hasta=YYYY-MM-DD]   (default)
- *   timeline --ids=id1,id2,...
- *   fetch    --id=<id>
- *
- * Salida: JSON a stdout. La base es la RAÍZ del proyecto (raizProyecto),
- * no el cwd crudo — misma semántica que los hooks (DT-HOOKS-RAIZ-GIT).
- */
-
-const ms = require('../../hooks/lib/memory-search');
-const { raizProyecto } = require('../../hooks/lib/raiz-proyecto');
-
-function memoriaSearch(opciones = {}) {
-  const op = (opciones._args && opciones._args[0]) || 'search';
-  const base = raizProyecto(process.cwd());
-
-  if (op === 'search') {
-    const query = opciones.query != null && opciones.query !== true ? String(opciones.query) : '';
-    if (!query) {
-      console.error('Error: falta --query="<términos>"');
-      process.exitCode = 1;
-      return;
-    }
-    const filtros = {};
-    const limit = parseInt(opciones.limit, 10);
-    if (!isNaN(limit) && limit > 0) filtros.limit = limit;
-    if (opciones.tipo != null && opciones.tipo !== true) filtros.tipo = String(opciones.tipo);
-    if (opciones.desde != null && opciones.desde !== true) filtros.fecha_desde = String(opciones.desde);
-    if (opciones.hasta != null && opciones.hasta !== true) filtros.fecha_hasta = String(opciones.hasta);
-    console.log(JSON.stringify(ms.search(base, query, filtros), null, 2));
-    return;
-  }
-
-  if (op === 'timeline') {
-    const ids = String(opciones.ids || '').split(',').map(s => s.trim()).filter(Boolean);
-    if (ids.length === 0) {
-      console.error('Error: falta --ids=id1,id2,...');
-      process.exitCode = 1;
-      return;
-    }
-    console.log(JSON.stringify(ms.timeline(base, ids), null, 2));
-    return;
-  }
-
-  if (op === 'fetch') {
-    if (opciones.id == null || opciones.id === true) {
-      console.error('Error: falta --id=<id>');
-      process.exitCode = 1;
-      return;
-    }
-    console.log(JSON.stringify(ms.fetch(base, String(opciones.id)), null, 2));
-    return;
-  }
-
-  console.error(`Error: op desconocida "${op}" (usa search|timeline|fetch)`);
-  process.exitCode = 1;
-}
-
-module.exports = memoriaSearch;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses memoria-search <op>` — búsqueda en la memoria del
+ * proyecto (.planning/sessions/, APRENDIZAJES.md, diary). Reemplaza los
+ * `require('./hooks/lib/memory-search')` relativos al proyecto que
+ * memoria-busqueda y benchmark-memoria instruían — rotos downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Ops:
+ *   search   --query="..." [--limit=N] [--tipo=aprendizaje|sesion|instinto]
+ *            [--desde=YYYY-MM-DD] [--hasta=YYYY-MM-DD]   (default)
+ *   timeline --ids=id1,id2,...
+ *   fetch    --id=<id>
+ *
+ * Salida: JSON a stdout. La base es la RAÍZ del proyecto (raizProyecto),
+ * no el cwd crudo — misma semántica que los hooks (DT-HOOKS-RAIZ-GIT).
+ */
+
+const ms = require('../../hooks/lib/memory-search');
+const { raizProyecto } = require('../../hooks/lib/raiz-proyecto');
+
+function memoriaSearch(opciones = {}) {
+  const op = (opciones._args && opciones._args[0]) || 'search';
+  const base = raizProyecto(process.cwd());
+
+  if (op === 'search') {
+    const query = opciones.query != null && opciones.query !== true ? String(opciones.query) : '';
+    if (!query) {
+      console.error('Error: falta --query="<términos>"');
+      process.exitCode = 1;
+      return;
+    }
+    const filtros = {};
+    const limit = parseInt(opciones.limit, 10);
+    if (!isNaN(limit) && limit > 0) filtros.limit = limit;
+    if (opciones.tipo != null && opciones.tipo !== true) filtros.tipo = String(opciones.tipo);
+    if (opciones.desde != null && opciones.desde !== true) filtros.fecha_desde = String(opciones.desde);
+    if (opciones.hasta != null && opciones.hasta !== true) filtros.fecha_hasta = String(opciones.hasta);
+    console.log(JSON.stringify(ms.search(base, query, filtros), null, 2));
+    return;
+  }
+
+  if (op === 'timeline') {
+    const ids = String(opciones.ids || '').split(',').map(s => s.trim()).filter(Boolean);
+    if (ids.length === 0) {
+      console.error('Error: falta --ids=id1,id2,...');
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify(ms.timeline(base, ids), null, 2));
+    return;
+  }
+
+  if (op === 'fetch') {
+    if (opciones.id == null || opciones.id === true) {
+      console.error('Error: falta --id=<id>');
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify(ms.fetch(base, String(opciones.id)), null, 2));
+    return;
+  }
+
+  console.error(`Error: op desconocida "${op}" (usa search|timeline|fetch)`);
+  process.exitCode = 1;
+}
+
+module.exports = memoriaSearch;

package/scripts/cli/nudge-accionar.js

@@ -1,39 +1,39 @@
-'use strict';
-
-/**
- * Subcomando `swl-ses nudge-accionar <id> --por <consumidor>` — cierra el
- * ciclo de un nudge (T-09, Fase 21 / ADR-0041).
- *
- * Lo invocan los comandos /swl:aprender y /swl:evolucionar (y el agente
- * auto-evolucion-swl) tras atender la sugerencia de un nudge, para que
- * `evolution/nudges.jsonl` registre quién lo accionó. Sin este cierre los
- * nudges se acumulan sin consumidor (174 emitidos / 0 accionados al crear
- * la Fase 21).
- *
- * Uso: swl-ses nudge-accionar <id> [--por <consumidor>]
- */
-
-const { marcarAccionado } = require('../lib/ciclo-autonomo/higiene-nudges');
-
-function nudgeAccionar(opciones = {}) {
-  const id = (opciones._args || [])[0];
-  const baseDir = opciones.dir || process.cwd();
-
-  if (!id) {
-    console.error('[nudge-accionar] falta el id. Uso: swl-ses nudge-accionar <id> [--por <consumidor>]');
-    process.exitCode = 1;
-    return null;
-  }
-
-  const por = opciones.por || opciones.by || 'desconocido';
-  const resultado = marcarAccionado(baseDir, { id, por });
-
-  if (resultado.marcados === 0) {
-    console.error(`[nudge-accionar] nudge "${id}" no encontrado o ya accionado`);
-  } else {
-    console.log(`[nudge-accionar] nudge "${id}" marcado como accionado por "${por}"`);
-  }
-  return resultado;
-}
-
-module.exports = nudgeAccionar;
+'use strict';
+
+/**
+ * Subcomando `swl-ses nudge-accionar <id> --por <consumidor>` — cierra el
+ * ciclo de un nudge (T-09, Fase 21 / ADR-0041).
+ *
+ * Lo invocan los comandos /swl:aprender y /swl:evolucionar (y el agente
+ * auto-evolucion-swl) tras atender la sugerencia de un nudge, para que
+ * `evolution/nudges.jsonl` registre quién lo accionó. Sin este cierre los
+ * nudges se acumulan sin consumidor (174 emitidos / 0 accionados al crear
+ * la Fase 21).
+ *
+ * Uso: swl-ses nudge-accionar <id> [--por <consumidor>]
+ */
+
+const { marcarAccionado } = require('../lib/ciclo-autonomo/higiene-nudges');
+
+function nudgeAccionar(opciones = {}) {
+  const id = (opciones._args || [])[0];
+  const baseDir = opciones.dir || process.cwd();
+
+  if (!id) {
+    console.error('[nudge-accionar] falta el id. Uso: swl-ses nudge-accionar <id> [--por <consumidor>]');
+    process.exitCode = 1;
+    return null;
+  }
+
+  const por = opciones.por || opciones.by || 'desconocido';
+  const resultado = marcarAccionado(baseDir, { id, por });
+
+  if (resultado.marcados === 0) {
+    console.error(`[nudge-accionar] nudge "${id}" no encontrado o ya accionado`);
+  } else {
+    console.log(`[nudge-accionar] nudge "${id}" marcado como accionado por "${por}"`);
+  }
+  return resultado;
+}
+
+module.exports = nudgeAccionar;

package/scripts/cli/run-eval.js

@@ -1,38 +1,38 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses run-eval` — ejecuta un eval del framework de validación
- * de outputs estructurados (scripts/run-eval.js). Reemplaza el
- * `node scripts/run-eval.js` relativo al proyecto que eval-framework
- * instruía — roto downstream (ver docs/invocacion-cli-cross-scope.md).
- *
- * Uso:
- *   swl-ses run-eval <ruta-eval.json>
- *   swl-ses run-eval --rebuild-aggregate
- *
- * ADVERTENCIA (nemesis iter-1 S3-6): el main() envuelto llama process.exit()
- * en todas sus ramas — este wrapper TERMINA el proceso host. Correcto vía
- * `bin/swl-ses.js` (proceso fresco por invocación); NO invocar in-process
- * (batch runners, tests que compongan varios wrappers) o matará el proceso.
- */
-
-const { main } = require('../run-eval.js');
-
-function runEval(opciones = {}) {
-  const args = [];
-  if (opciones['rebuild-aggregate'] || opciones.rebuild_aggregate) {
-    args.push('--rebuild-aggregate');
-  } else if (opciones._args && opciones._args[0]) {
-    args.push(String(opciones._args[0]));
-  }
-
-  const argvOriginal = process.argv;
-  process.argv = ['node', 'run-eval.js', ...args];
-  try {
-    main();
-  } finally {
-    process.argv = argvOriginal;
-  }
-}
-
-module.exports = runEval;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses run-eval` — ejecuta un eval del framework de validación
+ * de outputs estructurados (scripts/run-eval.js). Reemplaza el
+ * `node scripts/run-eval.js` relativo al proyecto que eval-framework
+ * instruía — roto downstream (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso:
+ *   swl-ses run-eval <ruta-eval.json>
+ *   swl-ses run-eval --rebuild-aggregate
+ *
+ * ADVERTENCIA (nemesis iter-1 S3-6): el main() envuelto llama process.exit()
+ * en todas sus ramas — este wrapper TERMINA el proceso host. Correcto vía
+ * `bin/swl-ses.js` (proceso fresco por invocación); NO invocar in-process
+ * (batch runners, tests que compongan varios wrappers) o matará el proceso.
+ */
+
+const { main } = require('../run-eval.js');
+
+function runEval(opciones = {}) {
+  const args = [];
+  if (opciones['rebuild-aggregate'] || opciones.rebuild_aggregate) {
+    args.push('--rebuild-aggregate');
+  } else if (opciones._args && opciones._args[0]) {
+    args.push(String(opciones._args[0]));
+  }
+
+  const argvOriginal = process.argv;
+  process.argv = ['node', 'run-eval.js', ...args];
+  try {
+    main();
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = runEval;

package/scripts/doctor.js

@@ -172,14 +172,37 @@ async function doctor(opciones = {}) {
   // en un cwd que no es un proyecto swl. Correr `doctor` desde un directorio
   // cualquiera no debe generar clutter. Marcadores de proyecto: .planning/ o
   // _userland/ ya presentes, o un install-state de scope proyecto.
-  const esProyectoSwl =
+  //
+  // El HOME es la EXCEPCIÓN: un install global crea ~/_userland ahí, pero el
+  // HOME NO es un proyecto — doctor no debe sembrar ~/.planning/ (bug 2026-07-15:
+  // sembraba un scaffold espurio y los hooks volcaban telemetría en el HOME vía
+  // raiz-proyecto). Ver scripts/lib/limpiar-basura-global.js.
+  const { esPlanningEspurio, esUserlandVacio, limpiarBasuraGlobal } = require('./lib/limpiar-basura-global');
+  const esHome = path.resolve(cwd) === path.resolve(require('os').homedir());
+  const esProyectoSwl = !esHome && (
     fs.existsSync(path.join(cwd, '.planning')) ||
     fs.existsSync(path.join(cwd, '_userland')) ||
-    fs.existsSync(path.join(cwd, '.swl-install-state.json'));
+    fs.existsSync(path.join(cwd, '.swl-install-state.json'))
+  );
 
   // 3. Verificar .planning/
   const planningDir = path.join(cwd, '.planning');
-  if (fs.existsSync(planningDir)) {
+  const basuraHome = [];
+  if (esHome && esPlanningEspurio(cwd)) basuraHome.push('~/.planning (scaffold de doctor)');
+  if (esHome && esUserlandVacio(cwd)) basuraHome.push('~/_userland (vacío)');
+  if (basuraHome.length > 0) {
+    // Basura de instalación global en el HOME: NO "reparar" (el HOME no es un
+    // proyecto) — OFRECER eliminarla. Ver scripts/lib/limpiar-basura-global.js.
+    console.log(formatearAdvertencia('instalación global', `Directorios basura en el HOME: ${basuraHome.join(', ')} — el HOME no es un proyecto`));
+    advertencias++;
+    reparables.push({
+      descripcion: `Eliminar ${basuraHome.length} directorio(s) basura del HOME: ${basuraHome.join(', ')}`,
+      reparar: () => {
+        const r = limpiarBasuraGlobal({ home: cwd });
+        return r.eliminados.length ? `Eliminado: ${r.eliminados.join(', ')}` : 'Nada que eliminar';
+      },
+    });
+  } else if (fs.existsSync(planningDir)) {
     const archivosEsperados = ['PROYECTO.md', 'REQUISITOS.md', 'HOJA-RUTA.md', 'ESTADO.md'];
     const faltantes = archivosEsperados.filter(
       f => !fs.existsSync(path.join(planningDir, f))