@saulwade/swl-ses 2.1.0 → 2.2.0

package/scripts/cli/loop-telemetry.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses loop-telemetry <op>` — telemetría de loops iterativos.
+ * Reemplaza los inline `require('./hooks/lib/loop-telemetry')` relativos al
+ * proyecto (rotos downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Ops:
+ *   iniciar   --tipo=X [--direccion=higher_is_better] [--config='{json}']  → imprime dir
+ *   registrar --dir=D --iteracion=N --metrica=M [--delta=D] [--estado=keep]
+ *             [--descripcion="..."]
+ *   handoff   --dir=D --source=X --status=Y [--findings='[json]'] [--config='{json}']
+ *   listar    (default) — resumen de las últimas 10 corridas
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const lt = require('../../hooks/lib/loop-telemetry');
+
+// Parseo no degradante: si el flag está presente pero su JSON es inválido,
+// reporta y devuelve {ok:false} en vez de silenciar a fallback (anti-fallback
+// silencioso). El fallback solo aplica cuando el flag está ausente.
+function parseJSON(v, fallback, flagName) {
+  if (v === undefined) return { ok: true, val: fallback };
+  try {
+    return { ok: true, val: JSON.parse(v) };
+  } catch (e) {
+    console.error(`[loop-telemetry] --${flagName} JSON inválido: ${e.message}`);
+    return { ok: false };
+  }
+}
+
+function requireDir(opciones) {
+  if (!opciones.dir) {
+    console.error('Error: falta --dir=<ruta>');
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+function loopTelemetry(opciones = {}) {
+  const op = (opciones._args && opciones._args[0]) || opciones.op || 'listar';
+
+  if (op === 'iniciar') {
+    const config = parseJSON(opciones.config, {}, 'config');
+    if (!config.ok) {
+      process.exitCode = 1;
+      return;
+    }
+    const r = lt.iniciarCorrida({
+      tipo: opciones.tipo,
+      direccion: opciones.direccion || 'higher_is_better',
+      config: config.val,
+    });
+    console.log(r.dir);
+    return;
+  }
+
+  if (op === 'registrar') {
+    if (!requireDir(opciones)) return;
+    const fila = {
+      iteracion: Number(opciones.iteracion),
+      metrica: Number(opciones.metrica),
+      estado: opciones.estado || 'keep',
+      descripcion: opciones.descripcion || '',
+    };
+    if (opciones.delta !== undefined) fila.delta = Number(opciones.delta);
+    lt.registrarIteracion(opciones.dir, fila);
+    console.log('[loop-telemetry] iteración registrada en ' + opciones.dir);
+    return;
+  }
+
+  if (op === 'handoff') {
+    if (!requireDir(opciones)) return;
+    const findings = parseJSON(opciones.findings, [], 'findings');
+    const config = parseJSON(opciones.config, {}, 'config');
+    if (!findings.ok || !config.ok) {
+      process.exitCode = 1;
+      return;
+    }
+    lt.escribirHandoff(opciones.dir, {
+      source: opciones.source,
+      status: opciones.status,
+      findings: findings.val,
+      config: config.val,
+    });
+    console.log('[loop-telemetry] handoff escrito en ' + opciones.dir);
+    return;
+  }
+
+  // listar (default)
+  const base = path.join(process.cwd(), lt.DIR_LOOPS);
+  let dirs = [];
+  try {
+    dirs = fs
+      .readdirSync(base)
+      .map((d) => path.join(base, d))
+      .filter((d) => fs.statSync(d).isDirectory());
+  } catch {
+    /* sin directorio de loops */
+  }
+  if (dirs.length === 0) {
+    console.log('(sin corridas de loops registradas)');
+    return;
+  }
+  for (const dir of dirs.sort().slice(-10)) {
+    try {
+      const t = lt.analizarTrayectoria(dir);
+      const h = lt.leerHandoff(dir);
+      console.log(
+        path.basename(dir) +
+          ' | iters: ' + t.totalIteraciones +
+          ' | keep/revert: ' + t.keeps + '/' + t.reverts +
+          ' | métrica: ' + t.metricaInicial + ' → ' + t.metricaFinal +
+          ' | plateau: ' + (t.plateau ? 'SÍ' : 'no') +
+          ' | status: ' + (h ? h.status : 'en curso')
+      );
+    } catch (e) {
+      console.log(path.basename(dir) + ' | (ilegible: ' + e.message + ')');
+    }
+  }
+}
+
+module.exports = loopTelemetry;

package/scripts/cli/mark-evolved.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses mark-evolved` — marca un componente SWL como evolucionado
+ * (frontmatter evolved: true + metadatos). Reemplaza el inline
+ * `require('./hooks/lib/evolution-tracker')` relativo al proyecto (roto
+ * downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses mark-evolved <ruta> [--from=VER] [--by=aprender]
+ *                           [--note="..."] [--rounds=N] [--score="A% → B%"]
+ */
+
+const path = require('node:path');
+const { markAsEvolved } = require('../../hooks/lib/evolution-tracker');
+
+function markEvolved(opciones = {}) {
+  const ruta = (opciones._args && opciones._args[0]) || opciones.ruta;
+  if (!ruta) {
+    console.error('Error: falta <ruta> del archivo a marcar');
+    process.exitCode = 1;
+    return;
+  }
+  // Guard anti path-traversal: la ruta debe resolver dentro del proyecto actual
+  // y ser un componente del sistema (.md/.json). Evita sobrescribir archivos
+  // arbitrarios con frontmatter si el flag se sintetiza desde input no confiable.
+  const cwd = process.cwd();
+  const resuelta = path.resolve(cwd, ruta);
+  if (resuelta !== cwd && !resuelta.startsWith(cwd + path.sep)) {
+    console.error('Error: la ruta debe estar dentro del proyecto actual');
+    process.exitCode = 1;
+    return;
+  }
+  if (!/\.(md|json)$/i.test(resuelta)) {
+    console.error('Error: solo se pueden marcar componentes .md o .json');
+    process.exitCode = 1;
+    return;
+  }
+  let from = opciones.from;
+  if (!from) {
+    try {
+      from = require(path.resolve(process.cwd(), 'package.json')).version;
+    } catch {
+      from = undefined;
+    }
+  }
+  const meta = { from, by: opciones.by || 'aprender' };
+  if (opciones.note) meta.note = opciones.note;
+  if (opciones.rounds) meta.rounds = Number(opciones.rounds);
+  if (opciones.score) meta.score = opciones.score;
+
+  const r = markAsEvolved(ruta, meta);
+  console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
+  if (!r.marked) process.exitCode = 1;
+}
+
+module.exports = markEvolved;

package/scripts/cli/metricas-dora.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses metricas-dora` — calcula métricas DORA del repo actual.
+ * Reemplaza `node scripts/lib/metricas-dora.js` relativo al proyecto (roto
+ * downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses metricas-dora [--json] [--dias=N]
+ */
+
+const { calcularDora, persistir } = require('../lib/metricas-dora');
+
+function metricasDora(opciones = {}) {
+  const dias = Number(opciones.dias);
+  const ventanaDias = Math.max(1, Math.min(365, Number.isFinite(dias) && dias > 0 ? dias : 30));
+  const baseDir = process.cwd();
+  const dora = calcularDora(baseDir, { ventanaDias });
+  try {
+    persistir(baseDir, dora);
+  } catch {
+    /* persistencia best-effort: no romper el informe si el disco falla */
+  }
+  console.log(JSON.stringify(dora, null, 2));
+}
+
+module.exports = metricasDora;

package/scripts/cli/near-duplicate.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses near-duplicate` — detecta si un aprendizaje nuevo es
+ * duplicado cercano de los existentes en APRENDIZAJES.md. Reemplaza el inline
+ * `require('./hooks/lib/fingerprint-id')` relativo al proyecto (roto downstream;
+ * ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses near-duplicate --texto="..." [--archivo=ruta] [--threshold=0.6]
+ *      echo "texto..." | swl-ses near-duplicate [--archivo=ruta]
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { isNearDuplicate } = require('../../hooks/lib/fingerprint-id');
+
+function nearDuplicate(opciones = {}) {
+  const archivo = opciones.archivo || '.planning/APRENDIZAJES.md';
+  let nuevo = opciones.texto;
+  if (!nuevo && !process.stdin.isTTY) {
+    try {
+      nuevo = fs.readFileSync(0, 'utf8');
+    } catch {
+      nuevo = '';
+    }
+  }
+  if (!nuevo) {
+    console.error('Error: falta --texto="..." o entrada por stdin');
+    process.exitCode = 1;
+    return;
+  }
+  // Guard anti path-traversal: --archivo debe resolver dentro del proyecto.
+  const cwd = process.cwd();
+  const resuelta = path.resolve(cwd, archivo);
+  if (resuelta !== cwd && !resuelta.startsWith(cwd + path.sep)) {
+    console.error('Error: --archivo debe estar dentro del proyecto actual');
+    process.exitCode = 1;
+    return;
+  }
+  let existentes = [];
+  try {
+    existentes = fs.readFileSync(resuelta, 'utf8').split(/^## /m).filter(Boolean);
+  } catch (e) {
+    // Sin archivo de aprendizajes legible: avisar (no degradar en silencio) y
+    // tratar todo como único.
+    if (e.code !== 'ENOENT') console.error('[near-duplicate] aviso: ' + e.code);
+  }
+  const t = Number(opciones.threshold);
+  const threshold = Number.isFinite(t) && t > 0 ? t : 0.6;
+
+  const r = isNearDuplicate(nuevo, existentes, threshold);
+  console.log(r.nearDuplicate ? 'DUPLICADO (sim=' + r.similarity + ')' : 'ÚNICO');
+}
+
+module.exports = nearDuplicate;

package/scripts/cli/notificaciones.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses notificaciones <op>` — gestiona las notificaciones
+ * Telegram y su bot daemon. Reemplaza los inline
+ * `require('./scripts/lib/notificaciones-telegram')` relativos al proyecto
+ * (rotos downstream; ver docs/invocacion-cli-cross-scope.md). Encapsula también
+ * el formato de salida que antes vivía en el comando.
+ *
+ * Ops:
+ *   init                  (requiere TTY)        bot-start
+ *   status                                      bot-stop
+ *   disable [--purge]                           bot-status
+ *   repair                                      bot-restart
+ *                                               bot-enable-autostart
+ *                                               bot-disable-autostart
+ */
+
+const nt = require('../lib/notificaciones-telegram');
+
+function imprimirStatus() {
+  const s = nt.status();
+  const botS = nt.botStatus();
+  const autostartLabel =
+    process.platform === 'win32'
+      ? 'Scheduled Task'
+      : process.platform === 'linux'
+        ? 'systemd --user'
+        : 'LaunchAgent';
+  const mudos = s.proyectosSilenciados.length
+    ? s.proyectosSilenciados.join(', ')
+    : 'ninguno';
+  console.log('');
+  console.log('Notificaciones Telegram — estado actual');
+  console.log('  .env:             ', s.envExiste ? 'existe' : 'no existe');
+  console.log('  token:            ', s.tokenConfigurado ? 'configurado' : 'no configurado');
+  console.log(
+    '  chat_id:          ',
+    s.chatIdConfigurado ? 'configurado (' + s.chatIdParcial + ')' : 'no configurado'
+  );
+  console.log('  proyectos mudos:  ', mudos);
+  console.log('  bot daemon:       ', botS.activo ? 'activo (PID ' + botS.pid + ')' : 'detenido');
+  console.log('  autostart:         usar /swl:notificaciones bot enable-autostart (' + autostartLabel + ')');
+  console.log('');
+}
+
+function imprimirBotStatus() {
+  const r = nt.botStatus();
+  console.log('');
+  console.log('Bot daemon — estado actual');
+  console.log('  activo:', r.activo ? 'sí' : 'no');
+  console.log('  pid:   ', r.pid !== null ? r.pid : 'n/a');
+  console.log('');
+}
+
+function reportarOk(prefijo, r, mensajeDefault) {
+  if (r.ok) {
+    console.log('[' + prefijo + ']', r.mensaje || mensajeDefault);
+  } else {
+    console.error('[' + prefijo + '] Error:', r.error);
+    process.exitCode = 1;
+  }
+}
+
+// Tabla de dispatch de los ops del bot daemon: [prefijo, fn, mensajeDefault].
+const BOT_OPS = {
+  'bot-start': ['bot', () => nt.botStart(), 'Bot iniciado.'],
+  'bot-stop': ['bot', () => nt.botStop(), 'Bot detenido.'],
+  'bot-restart': ['bot', () => nt.botRestart(), 'Bot reiniciado.'],
+  'bot-enable-autostart': ['autostart', () => nt.botEnableAutostart(), 'Autostart habilitado.'],
+  'bot-disable-autostart': ['autostart', () => nt.botDisableAutostart(), 'Autostart deshabilitado.'],
+};
+
+async function notificaciones(opciones = {}) {
+  const op = (opciones._args && opciones._args[0]) || opciones.op || 'status';
+
+  if (BOT_OPS[op]) {
+    const [prefijo, fn, msg] = BOT_OPS[op];
+    reportarOk(prefijo, fn(), msg);
+    return;
+  }
+
+  switch (op) {
+    case 'init': {
+      if (!process.stdin.isTTY) {
+        console.log('Este subcomando requiere entrada interactiva (TTY).');
+        console.log('Ejecuta desde tu terminal:');
+        console.log('  swl-ses notificaciones init');
+        console.log('O usa el instalador:');
+        console.log('  npx -y @saulwade/swl-ses@latest install');
+        return;
+      }
+      const r = await nt.init({ esTty: true });
+      console.log('[resultado]', r.resultado, r.detalle || '');
+      if (r.resultado === 'error') process.exitCode = 1;
+      return;
+    }
+    case 'status':
+      imprimirStatus();
+      return;
+    case 'disable': {
+      const r = nt.disable({ confirmar: true, conservarEnv: !opciones.purge });
+      console.log('[resultado]', r.resultado, r.detalle || '');
+      if (r.resultado === 'error') process.exitCode = 1;
+      return;
+    }
+    case 'repair': {
+      const r = await nt.repair();
+      console.log('[repair]', r.resultado, r.detalle || '');
+      if (r.resultado === 'error') process.exitCode = 1;
+      return;
+    }
+    case 'bot-status':
+      imprimirBotStatus();
+      return;
+    default:
+      console.error('Op desconocida: ' + op);
+      console.error('Ops: init|status|disable|repair|bot-start|bot-stop|bot-status|bot-restart|bot-enable-autostart|bot-disable-autostart');
+      process.exitCode = 1;
+  }
+}
+
+module.exports = notificaciones;

package/scripts/cli/propose-step.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * Wrapper CLI para `swl-ses propose-step` — anexo propositivo del RESUMEN de
+ * fase (ADR-0037). Envuelve hooks/lib/propose-step.js (que lee process.argv).
+ *
+ * Reemplaza el `node hooks/lib/propose-step.js --rango=...` relativo al proyecto
+ * que /swl:ejecutar-fase invocaba — roto downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses propose-step --rango=<base>..HEAD   (opt-out SWL_PROPOSE=0)
+ */
+
+const { main } = require('../../hooks/lib/propose-step.js');
+
+function proposeStep(opciones = {}) {
+  opciones = opciones || {};
+  const args = ['node', 'propose-step'];
+  if (opciones.rango) args.push(`--rango=${opciones.rango}`);
+  const argvOriginal = process.argv;
+  process.argv = args;
+  try {
+    return main(process.argv);
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = proposeStep;

package/scripts/cli/schedule-parse.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses schedule-parse` — parsea una frase en inglés a expresión
+ * cron. Reemplaza el inline `require('./scripts/lib/schedule-parser')` relativo
+ * al proyecto (roto downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses schedule-parse "every morning at 9am"
+ */
+
+const { parseNaturalSchedule } = require('../lib/schedule-parser');
+
+function scheduleParse(opciones = {}) {
+  const frase =
+    (opciones._args && opciones._args.join(' ')) || opciones.texto || '';
+  console.log(JSON.stringify(parseNaturalSchedule(frase), null, 2));
+}
+
+module.exports = scheduleParse;

package/scripts/cli/sugerir-modelo.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses sugerir-modelo` — evalúa la complejidad de una tarea y
+ * sugiere el modelo (opus/sonnet/haiku). Reemplaza el inline
+ * `require('./hooks/lib/model-router.js')` relativo al proyecto (roto downstream;
+ * ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses sugerir-modelo "<descripción de la tarea>"
+ */
+
+const { sugerirModelo } = require('../../hooks/lib/model-router.js');
+
+function sugerirModeloCli(opciones = {}) {
+  const desc =
+    (opciones._args && opciones._args.join(' ')) || opciones.desc || '';
+  console.log(JSON.stringify(sugerirModelo(desc), null, 2));
+}
+
+module.exports = sugerirModeloCli;

package/scripts/cli/verificar-plan.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Subcomando `swl-ses verificar-plan --fase=N` — verificación read-only del lock
+ * de un PLAN (gate G1). Lo usa /swl:ejecutar-fase antes de implementar y
+ * /swl:aprobar-plan Paso 2 para detectar planes ya firmados/mutados/legacy.
+ *
+ * Reemplaza el `node -e "require('./scripts/lib/plan-lock')"` inline que se
+ * rompía downstream (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Exit 0 si ok (firmado o legacy); exit 1 si mutado/sin-firmar/corrupto.
+ *
+ * Uso: swl-ses verificar-plan --fase=N [--plan=<ruta>]
+ */
+
+const { verificarPlan } = require('../lib/plan-lock');
+const { resolverPlanPath } = require('../lib/resolver-plan-fase');
+
+function verificarPlanCli(opciones = {}) {
+  opciones = opciones || {};
+  const planPath = resolverPlanPath(opciones);
+  if (!planPath) {
+    console.error('Uso: swl-ses verificar-plan --fase=N [--plan=<ruta>]');
+    process.exit(1);
+  }
+  const r = verificarPlan(planPath);
+  console.log(JSON.stringify(r, null, 2));
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = verificarPlanCli;
+
+if (require.main === module) {
+  const { parsearOpciones } = require('../lib/parsear-opciones');
+  verificarPlanCli(parsearOpciones(process.argv.slice(2)));
+}

package/scripts/cli/verificar-trazabilidad.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Wrapper CLI para el subcomando `swl-ses verificar-trazabilidad`.
+ *
+ * Traduce las opciones parseadas del bin a las flags que espera el script
+ * standalone `scripts/verificar-trazabilidad.js` (que lee process.argv y hace
+ * su propio process.exit). Mismo patrón que scripts/cli/audit-claudemd.js.
+ *
+ * Reemplaza el `node scripts/verificar-trazabilidad.js` relativo al proyecto que
+ * /swl:aprobar-plan invocaba — roto downstream (ver
+ * docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses verificar-trazabilidad --fase=N [--solo-plan] [--json]
+ */
+
+const { main } = require('../verificar-trazabilidad.js');
+
+function verificarTrazabilidad(opciones = {}) {
+  opciones = opciones || {};
+  const args = [];
+  if (opciones.fase != null && opciones.fase !== true) args.push(`--fase=${opciones.fase}`);
+  if (opciones['solo-plan'] || opciones.solo_plan) args.push('--solo-plan');
+  if (opciones.json) args.push('--json');
+
+  const argvOriginal = process.argv;
+  process.argv = ['node', 'verificar-trazabilidad.js', ...args];
+  try {
+    main();
+  } finally {
+    process.argv = argvOriginal;
+  }
+}
+
+module.exports = verificarTrazabilidad;

package/scripts/derivar-feature-list.js

@@ -486,4 +486,5 @@ module.exports = {
   enriquecerDesdeFases,
   generarFeatureList,
   normalizarEstado,
+  main,
 };

package/scripts/lib/auditar-invocaciones-comandos.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * auditar-invocaciones-comandos.js
+ *
+ * Gate anti-regresión de la clase de bug "invocación relativa al proyecto en
+ * comandos user-facing" (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Un comando que corre en el proyecto del usuario NUNCA debe invocar scripts SWL
+ * con ruta relativa al proyecto (`node scripts/lib/...`, `node hooks/...`,
+ * `require('./scripts/...')`): esas rutas no existen downstream. Debe usar el
+ * subcomando del CLI (`swl-ses <sub>` / `npx ... <sub>` / `node scripts/cli/<sub>.js`).
+ *
+ * Solo escanea bloques de código (``` ... ```) para no marcar menciones
+ * prohibitivas en prosa. Excluye `scripts/cli/` (forma repo-madre sancionada).
+ *
+ * Función pura + entrypoint CLI con exit 1 si hay violaciones.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Comandos que corren SOLO en el repo madre de swl-ses (el CWD ES el repo, así
+// que `node scripts/...` relativo es correcto). NO son user-facing.
+const SELF_DEV = new Set([
+  'release',
+  'contribuir',
+  'evaluar-skill',
+  'reflect-skills',
+]);
+
+// Patrones de invocación relativa al proyecto que se rompen downstream.
+// Se evalúan SOLO dentro de bloques de código.
+const PATRONES = [
+  { re: /\bnode\s+(?:\.\/)?scripts\/(?!cli\/)/, desc: 'node scripts/ (usa swl-ses <sub>)' },
+  { re: /\bnode\s+(?:\.\/)?hooks\//, desc: 'node hooks/ (usa swl-ses <sub>)' },
+  { re: /require\(\s*['"]\.\.?\/scripts\//, desc: "require('./scripts/ inline" },
+  { re: /require\(\s*['"]\.\.?\/hooks\//, desc: "require('./hooks/ inline" },
+];
+
+/**
+ * @param {string} [comandosDir] default: comandos/swl relativo al repo de este script.
+ * @returns {{ok:boolean, violaciones:Array<{comando:string,linea:number,texto:string,patron:string}>, escaneados:number}}
+ */
+function auditarInvocacionesComandos(comandosDir) {
+  const dir = comandosDir || path.join(__dirname, '..', '..', 'comandos', 'swl');
+  const violaciones = [];
+  let escaneados = 0;
+
+  let archivos;
+  try {
+    archivos = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
+  } catch {
+    return { ok: true, violaciones, escaneados: 0 };
+  }
+
+  for (const archivo of archivos) {
+    const comando = archivo.replace(/\.md$/, '');
+    if (SELF_DEV.has(comando)) continue;
+    escaneados++;
+
+    const contenido = fs.readFileSync(path.join(dir, archivo), 'utf8');
+    const lineas = contenido.split('\n');
+    let dentroCodigo = false;
+
+    for (let i = 0; i < lineas.length; i++) {
+      const linea = lineas[i];
+      if (/^\s*```/.test(linea)) {
+        dentroCodigo = !dentroCodigo;
+        continue;
+      }
+      if (!dentroCodigo) continue;
+      for (const { re, desc } of PATRONES) {
+        if (re.test(linea)) {
+          violaciones.push({
+            comando,
+            linea: i + 1,
+            texto: linea.trim(),
+            patron: desc,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { ok: violaciones.length === 0, violaciones, escaneados };
+}
+
+module.exports = { auditarInvocacionesComandos, SELF_DEV };
+
+if (require.main === module) {
+  const r = auditarInvocacionesComandos();
+  if (r.ok) {
+    console.log(`[OK] invocaciones-comandos — ${r.escaneados} comandos user-facing sin rutas relativas al proyecto`);
+    process.exit(0);
+  }
+  console.error(`[FALLA] invocaciones-comandos — ${r.violaciones.length} invocación(es) relativa(s) al proyecto en comandos user-facing:`);
+  for (const v of r.violaciones) {
+    console.error(`  ${v.comando}.md:${v.linea} [${v.patron}] ${v.texto}`);
+  }
+  console.error('\nUsa el patrón cross-scope (docs/invocacion-cli-cross-scope.md): swl-ses <sub> / npx ... <sub> / node scripts/cli/<sub>.js');
+  process.exit(1);
+}

package/scripts/lib/resolver-plan-fase.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * resolver-plan-fase.js
+ *
+ * Resuelve la ruta del PLAN.md de una fase a partir de las opciones del CLI.
+ * Compartido por los subcomandos `aprobar-plan` y `verificar-plan`.
+ *
+ * Acepta `--plan=<ruta>` explícito o `--fase=N` (deriva
+ * `.planning/fases/0N-PLAN.md`, con fallback sin cero a la izquierda).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * @param {{plan?:string, fase?:(string|number|boolean)}} [opciones]
+ * @returns {string|null} ruta al PLAN, o null si no se pudo derivar.
+ */
+function resolverPlanPath(opciones = {}) {
+  if (opciones && opciones.plan && typeof opciones.plan === 'string') {
+    return opciones.plan;
+  }
+  const fase = opciones ? opciones.fase : undefined;
+  if (fase == null || fase === true) return null;
+  const n = String(fase).padStart(2, '0');
+  const candidatos = [
+    path.join('.planning', 'fases', `${n}-PLAN.md`),
+    path.join('.planning', 'fases', `${fase}-PLAN.md`),
+  ];
+  for (const c of candidatos) {
+    if (fs.existsSync(c)) return c;
+  }
+  return candidatos[0];
+}
+
+module.exports = { resolverPlanPath };