@saulwade/swl-ses 2.5.2 → 2.6.0

package/scripts/lib/activar-hooks-proyecto.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * activar-hooks-proyecto.js — Camino "solo hooks" (DT-HOOKS-SOLO-PROYECTO).
+ *
+ * Registra en el `.claude/settings.json` del PROYECTO los hooks del scope
+ * GLOBAL ya instalado, sin copiar ningún componente. Cierra el dilema del
+ * install local: los hooks solo funcionan registrados a nivel proyecto
+ * (ADR-0009), pero el install local completo duplica agentes/comandos en la
+ * UI de Claude Code (lee ambos scopes). Con este camino:
+ *
+ *   - Los comandos del settings apuntan con ruta ABSOLUTA al hooks/ global
+ *     (esGlobal: true en registrarHooks) → cero archivos copiados.
+ *   - `swl-ses update` del global refresca los hooks de TODOS los proyectos
+ *     activados así, gratis (apuntan a los mismos archivos).
+ *   - Hooks externos (no-SWL) del settings del proyecto se preservan
+ *     (garantía de registrarHooks).
+ *
+ * Uso: `swl-ses install --target claude --solo-hooks` (en la raíz del
+ * proyecto). Requiere instalación global previa del runtime.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RUNTIMES_SOPORTADOS = new Set(['claude', 'openclaude']);
+
+/**
+ * @param {object} opciones
+ * @param {string} [opciones.target='claude']     Runtime (claude|openclaude — formato de settings de Claude Code)
+ * @param {string} [opciones.dirProyecto=cwd]     Raíz del proyecto destino
+ * @param {string} [opciones.hooksDirGlobal]      Override del hooks/ global (tests)
+ * @param {object} [opciones.deps]                Inyección para tests: { registrarHooks, registrarOptimizaciones, cargarHooksConfig, scopesReales, obtenerRuntime }
+ * @returns {{ok: boolean, error?: string, settingsPath?: string, hooksDirGlobal?: string, registrados?: number, preservados?: number}}
+ */
+function activarHooksProyecto(opciones = {}) {
+  const target = opciones.target || 'claude';
+  if (!RUNTIMES_SOPORTADOS.has(target)) {
+    return { ok: false, error: `--solo-hooks soporta por ahora targets con settings formato Claude Code (claude, openclaude); recibido: "${target}".` };
+  }
+
+  const deps = opciones.deps || {};
+  const hs = require('./hooks-settings');
+  const registrarHooks = deps.registrarHooks || hs.registrarHooks;
+  const registrarOptimizaciones = deps.registrarOptimizaciones || hs.registrarOptimizaciones;
+  const cargarHooksConfig = deps.cargarHooksConfig || hs.cargarHooksConfig;
+
+  // 1. Localizar el hooks/ del scope GLOBAL del runtime.
+  let hooksDirGlobal = opciones.hooksDirGlobal;
+  if (!hooksDirGlobal) {
+    try {
+      const dr = require('./detectar-runtime');
+      const obtenerRuntime = deps.obtenerRuntime || dr.obtenerRuntime;
+      const scopesReales = deps.scopesReales || dr.scopesReales;
+      const runtime = obtenerRuntime(target);
+      const global = scopesReales(runtime).find(s => s.esGlobal);
+      if (!global) return { ok: false, error: `No se pudo resolver el scope global del runtime "${target}".` };
+      hooksDirGlobal = path.join(global.dir, 'hooks');
+    } catch (err) {
+      return { ok: false, error: `No se pudo detectar el runtime "${target}": ${err.message}` };
+    }
+  }
+  if (!fs.existsSync(hooksDirGlobal)) {
+    return { ok: false, error: `No hay instalación global con hooks en ${hooksDirGlobal}. Instala primero el global: npx -y @saulwade/swl-ses@latest install --target ${target} --global --perfil completo` };
+  }
+
+  // 2. Hooks disponibles = archivos del global ∩ hooks-config del paquete.
+  const hooksConfig = cargarHooksConfig();
+  const hookFiles = fs.readdirSync(hooksDirGlobal)
+    .filter(f => f.endsWith('.js') && hooksConfig[f]);
+  if (hookFiles.length === 0) {
+    return { ok: false, error: `El hooks/ global (${hooksDirGlobal}) no contiene hooks reconocidos por hooks-config.json — instalación global corrupta o muy antigua; corre update primero.` };
+  }
+
+  // 3. Registrar en el settings.json del PROYECTO, apuntando al global.
+  const dirProyecto = opciones.dirProyecto || process.cwd();
+  const dirClaude = path.join(dirProyecto, '.claude');
+  fs.mkdirSync(dirClaude, { recursive: true });
+  const settingsPath = path.join(dirClaude, 'settings.json');
+
+  const r = registrarHooks({
+    settingsPath,
+    hooksDir: hooksDirGlobal,
+    esGlobal: true, // semántica: comandos con ruta ABSOLUTA al hooksDir (que es el global)
+    hookFiles,
+  });
+
+  let optimizaciones = 0;
+  try {
+    const opt = registrarOptimizaciones(settingsPath);
+    optimizaciones = (opt && opt.registradas) || 0;
+  } catch { /* opcional — no bloquea la activación */ }
+
+  // 4. Sembrar el .gitignore del proyecto: encender la telemetría hace que
+  // los hooks ESCRIBAN (.planning/METRICAS.md, audit*.jsonl, evolution/...)
+  // — sin la sección swl-ses esos archivos runtime aparecen como cambios
+  // pendientes en el editor del usuario (caso real sistema-verificacion-oic,
+  // 2026-07-10: 19 archivos sin trackear tras activar hooks).
+  let gitignorePath = null;
+  try {
+    const { actualizarGitignore } = deps.gitignoreManifest || require('./gitignore-manifest');
+    gitignorePath = actualizarGitignore(dirProyecto);
+  } catch { /* no bloquea la activación — se reporta null */ }
+
+  return {
+    ok: true,
+    settingsPath,
+    hooksDirGlobal,
+    registrados: r.registrados,
+    preservados: r.preservados,
+    optimizaciones,
+    gitignorePath,
+  };
+}
+
+module.exports = { activarHooksProyecto, RUNTIMES_SOPORTADOS };

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

@@ -87,17 +87,107 @@ function auditarInvocacionesComandos(comandosDir) {
   return { ok: violaciones.length === 0, violaciones, escaneados };
 }
 
-module.exports = { auditarInvocacionesComandos, SELF_DEV };
+// Skills que corren SOLO en el repo madre (host-only declarado en su propio
+// frontmatter/cuerpo): sus `node scripts/...` son legítimos porque el CWD ES
+// el repo (DT-PATHS-DESTINO, cierre 2026-07-10).
+const SKILLS_SOLO_MADRE = new Set([
+  'doc-sync',
+  'release-semver',
+  'validacion-ci-sistema',
+]);
+
+// Lenguajes de fence que se auditan en skills: solo instrucciones ejecutables
+// de shell. Los bloques js/javascript documentan APIs de módulos (referencia,
+// no comandos a ejecutar downstream) y llevan su clarificador de layout.
+const LENGUAJES_EJECUTABLES = new Set(['', 'bash', 'sh', 'shell']);
+
+/**
+ * Igual que auditarInvocacionesComandos pero sobre habilidades/<skill>/SKILL.md.
+ * Solo audita fences ejecutables (bash/sh/shell/sin lenguaje).
+ * @param {string} [habilidadesDir]
+ * @returns {{ok:boolean, violaciones:Array<{comando:string,linea:number,texto:string,patron:string}>, escaneados:number}}
+ */
+function auditarInvocacionesSkills(habilidadesDir) {
+  const dir = habilidadesDir || path.join(__dirname, '..', '..', 'habilidades');
+  const violaciones = [];
+  let escaneados = 0;
+
+  let skills;
+  try {
+    skills = fs.readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return { ok: true, violaciones, escaneados: 0 };
+  }
+
+  for (const skill of skills) {
+    if (SKILLS_SOLO_MADRE.has(skill)) continue;
+    const ruta = path.join(dir, skill, 'SKILL.md');
+    let contenido;
+    try {
+      contenido = fs.readFileSync(ruta, 'utf8');
+    } catch {
+      continue;
+    }
+    escaneados++;
+
+    const lineas = contenido.split('\n');
+    let dentroCodigo = false;
+    let lenguaje = '';
+    let marcadores = 0;
+
+    for (let i = 0; i < lineas.length; i++) {
+      const linea = lineas[i];
+      const fence = linea.match(/^\s*```\s*(\S*)/);
+      if (fence) {
+        marcadores++;
+        dentroCodigo = !dentroCodigo;
+        lenguaje = dentroCodigo ? fence[1].toLowerCase() : '';
+        continue;
+      }
+      if (!dentroCodigo || !LENGUAJES_EJECUTABLES.has(lenguaje)) continue;
+      for (const { re, desc } of PATRONES) {
+        if (re.test(linea)) {
+          violaciones.push({
+            comando: `habilidades/${skill}/SKILL.md`,
+            linea: i + 1,
+            texto: linea.trim(),
+            patron: desc,
+          });
+          break;
+        }
+      }
+    }
+    // Fences desbalanceados (conteo impar de ```): el toggle booleano quedó
+    // invertido para el resto del archivo y pudo silenciar violaciones reales.
+    // Se reporta como violación para que el scan NO termine en verde falso.
+    if (marcadores % 2 !== 0) {
+      violaciones.push({
+        comando: `habilidades/${skill}/SKILL.md`,
+        linea: 0,
+        texto: `${marcadores} marcadores \`\`\` (impar) — fence sin cerrar o anidado`,
+        patron: 'fences desbalanceados (el scan de invocaciones pudo quedar ciego)',
+      });
+    }
+  }
+
+  return { ok: violaciones.length === 0, violaciones, escaneados };
+}
+
+module.exports = { auditarInvocacionesComandos, auditarInvocacionesSkills, SELF_DEV, SKILLS_SOLO_MADRE };
 
 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`);
+  const rs = auditarInvocacionesSkills();
+  if (r.ok && rs.ok) {
+    console.log(`[OK] invocaciones-comandos — ${r.escaneados} comandos + ${rs.escaneados} skills 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}`);
+  const todas = [...r.violaciones, ...rs.violaciones];
+  console.error(`[FALLA] invocaciones-comandos — ${todas.length} invocación(es) relativa(s) al proyecto en componentes user-facing:`);
+  for (const v of todas) {
+    console.error(`  ${v.comando}:${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/ciclo-autonomo/candidatos.js

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * candidatos.js — Detector determinista de candidatos a Fase B del ciclo
+ * autónomo (Fase 22, T-02, ADR-0042 gate G-B, REQ-22-01).
+ *
+ * Tres fuentes deterministas, SIN invocar LLM:
+ *   1. Instintos con `candidato_global:true` en `instintos/proyecto.yaml`
+ *      (via `yaml-instintos.leerInstintos`, tolerante a archivo ausente).
+ *   2. Nudges `kind:'auto-evolucion'` no accionados con evidencia
+ *      (`data.diagnosis` o `data.razon` en {fallos, loop}) leídos de
+ *      `evolution/nudges.jsonl`.
+ *   3. Skills fríos vía `require('../skill-metrics').skillsStale` (require
+ *      tolerante → `[]` si la lib no resuelve en el destino de instalación).
+ *
+ * Persiste SOLO los candidatos nuevos (dedupe por `id`, releyendo el jsonl
+ * previo con tolerancia por línea) en `evolution/candidatos-fase-b.jsonl`.
+ * Una corrida sin candidatos nuevos NO escribe el archivo (ni lo crea si no
+ * existía). Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/candidatos
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { leerInstintos } = require('./yaml-instintos');
+
+const RUTA_INSTINTOS_RELATIVA = path.join('instintos', 'proyecto.yaml');
+const RUTA_NUDGES_RELATIVA = path.join('.planning', 'evolution', 'nudges.jsonl');
+const RUTA_CANDIDATOS_RELATIVA = path.join('.planning', 'evolution', 'candidatos-fase-b.jsonl');
+
+/** Razones de nudge `auto-evolucion` que cuentan como evidencia suficiente. */
+const RAZONES_CON_EVIDENCIA = new Set(['fallos', 'loop']);
+
+/** Lee un JSONL con tolerancia por línea: línea corrupta se descarta, nunca crashea. */
+function leerJsonlTolerante(ruta) {
+  let crudo;
+  try {
+    crudo = fs.readFileSync(ruta, 'utf8');
+  } catch (_) {
+    return [];
+  }
+  return crudo.split(/\r\n|\n/)
+    .filter((linea) => linea.trim() !== '')
+    .map((linea) => {
+      try {
+        return JSON.parse(linea);
+      } catch (_) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/** Fuente 1: instintos con `candidato_global:true` en instintos/proyecto.yaml. */
+function candidatosDeInstintos(baseDir, ts) {
+  const ruta = path.join(baseDir, RUTA_INSTINTOS_RELATIVA);
+  let datos;
+  try {
+    datos = leerInstintos(ruta);
+  } catch (_) {
+    return []; // archivo ausente o YAML corrupto: sin candidatos de esta fuente
+  }
+
+  return (datos.instintos || [])
+    .filter((instinto) => instinto.candidato_global === true)
+    .map((instinto) => ({
+      id: `instinto:${instinto.id}`,
+      fuente: 'instinto-global',
+      ref: { id: instinto.id, pattern: instinto.pattern || null },
+      ts,
+      origen: 'ciclo-autonomo',
+    }));
+}
+
+/** Fuente 2: nudges `kind:'auto-evolucion'` no accionados con evidencia. */
+function candidatosDeNudges(baseDir, ts) {
+  const ruta = path.join(baseDir, RUTA_NUDGES_RELATIVA);
+
+  return leerJsonlTolerante(ruta)
+    .filter((nudge) => nudge && nudge.kind === 'auto-evolucion' && nudge.accionado !== true)
+    .filter((nudge) => {
+      const data = nudge.data || {};
+      return Boolean(data.diagnosis) || RAZONES_CON_EVIDENCIA.has(data.razon);
+    })
+    .map((nudge) => ({
+      id: `nudge:${nudge.id}`,
+      fuente: 'evolucion-agente',
+      ref: {
+        target: nudge.target || null,
+        razon: (nudge.data || {}).razon || null,
+        tieneDiagnosis: Boolean((nudge.data || {}).diagnosis),
+      },
+      ts,
+      origen: 'ciclo-autonomo',
+    }));
+}
+
+/** Fuente 3: skills fríos vía skill-metrics.skillsStale (require tolerante → []). */
+function candidatosDeSkillsFrios(baseDir, ahora, ts) {
+  let skillsStale;
+  try {
+    ({ skillsStale } = require('../skill-metrics'));
+  } catch (_) {
+    return []; // lib no distribuida en este destino: sin candidatos de esta fuente
+  }
+
+  let frios;
+  try {
+    frios = skillsStale(baseDir, ahora);
+  } catch (_) {
+    return [];
+  }
+
+  return (frios || []).map((frio) => ({
+    id: `skill:${frio.skill}`,
+    fuente: 'skill-stale',
+    ref: { skill: frio.skill, diasInactivo: frio.diasInactivo },
+    ts,
+    origen: 'ciclo-autonomo',
+  }));
+}
+
+/** Ids ya persistidos en `candidatos-fase-b.jsonl` (dedupe, tolerante por línea). */
+function idsConocidos(baseDir) {
+  const ruta = path.join(baseDir, RUTA_CANDIDATOS_RELATIVA);
+  return new Set(leerJsonlTolerante(ruta).map((entrada) => entrada.id).filter(Boolean));
+}
+
+/** Append de los candidatos nuevos (dedupe ya aplicado por el caller); no-op si viene vacío. */
+function persistirNuevos(baseDir, nuevos) {
+  if (nuevos.length === 0) return;
+
+  const ruta = path.join(baseDir, RUTA_CANDIDATOS_RELATIVA);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const lineas = nuevos.map((candidato) => JSON.stringify(candidato)).join('\n') + '\n';
+  fs.appendFileSync(ruta, lineas);
+}
+
+/**
+ * Detecta candidatos a Fase B desde las tres fuentes deterministas y
+ * persiste (dedupe por id) SOLO los nuevos en `evolution/candidatos-fase-b.jsonl`.
+ * Tolerante a la ausencia de cualquier fuente — nunca crashea.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{nuevos: number, total: number, candidatos: object[]}}
+ */
+function detectar(baseDir, { ahora } = {}) {
+  const momento = ahora || new Date();
+  const ts = momento.toISOString();
+
+  const candidatos = [
+    ...candidatosDeInstintos(baseDir, ts),
+    ...candidatosDeNudges(baseDir, ts),
+    ...candidatosDeSkillsFrios(baseDir, momento, ts),
+  ];
+
+  const conocidos = idsConocidos(baseDir);
+  const vistos = new Set();
+  const nuevosCandidatos = candidatos.filter((candidato) => {
+    if (conocidos.has(candidato.id) || vistos.has(candidato.id)) return false;
+    vistos.add(candidato.id);
+    return true;
+  });
+
+  persistirNuevos(baseDir, nuevosCandidatos);
+
+  return { nuevos: nuevosCandidatos.length, total: candidatos.length, candidatos };
+}
+
+module.exports = { detectar };

package/scripts/lib/ciclo-autonomo/config.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * Loader/writer de `.planning/evolution/ciclo-config.json` — schema del
+ * motor determinista de aprendizaje (Fase 21, ADR-0041/ADR-0042, Nivel 0).
+ *
+ * Opt-OUT estricto (decisión del usuario 2026-07-10, reformula la regla de
+ * negocio 1 de la Fase 21): el motor NACE ENCENDIDO — "un ciclo que exige
+ * encendido es un ciclo muerto en downstream". Kill-switch doble:
+ * `habilitado:false` en el config (vía `/swl:evolucion-continua off`) o
+ * `SWL_CICLO_AUTONOMO=0` por sesión. Esta lib solo expone el predicado
+ * `estaHabilitado()`; el único punto que lo consulta para decidir si
+ * ejecutar es el orquestador (T-07, `index.js`) — las libs de sub-fase
+ * (writer, drenador, puente) son puras y no consultan config.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/config
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteJSON } = require('../../../hooks/lib/atomic-write');
+
+/** Ruta relativa del archivo de config dentro del baseDir del proyecto. */
+const CONFIG_RELATIVA = path.join('.planning', 'evolution', 'ciclo-config.json');
+
+/** Valores aceptados para el campo `credencial` (dual: cuenta Claude o API key). */
+const CREDENCIALES_VALIDAS = new Set(['cuenta', 'api-key']);
+
+/**
+ * Defaults del schema completo. Los campos LLM (`presupuesto_usd_mes`,
+ * `tope_mutaciones_corrida`) nacieron reservados en Fase 21 y se consumen a
+ * partir de Fase 22. Los campos `fase_b_habilitada`, `last_run_fase_b`,
+ * `gasto_mes`, `mes` y `pausado_por_presupuesto` son propios de Fase 22
+ * (headless plumbing, ADR-0042 gate G-B): `fase_b_habilitada` nace en `true`
+ * —kill-switch separado del motor, coherente con el opt-out estricto general
+ * (default encendido)—; `gasto_mes`/`mes` llevan el contador de presupuesto
+ * del mes en curso (clave `mes` en formato `YYYY-MM` local); `mes:null`
+ * fuerza el primer `registrarGasto` a inicializar el mes actual.
+ */
+const DEFAULTS = Object.freeze({
+  habilitado: true,
+  credencial: 'cuenta',
+  presupuesto_usd_mes: 10,
+  tope_mutaciones_corrida: 3,
+  last_run: null,
+  ultima_corrida: null,
+  fase_b_habilitada: true,
+  last_run_fase_b: null,
+  gasto_mes: 0,
+  mes: null,
+  pausado_por_presupuesto: false,
+});
+
+/**
+ * Resuelve la ruta absoluta del archivo de config para un baseDir dado.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto (normalmente cwd).
+ * @returns {string} Ruta absoluta a `ciclo-config.json`.
+ */
+function rutaConfig(baseDir) {
+  return path.join(baseDir, CONFIG_RELATIVA);
+}
+
+/**
+ * Normaliza el campo `credencial`: valor fuera del dominio válido cae a
+ * "cuenta" sin lanzar error — un config corrupto o editado a mano nunca
+ * debe crashear al motor.
+ *
+ * @param {*} valor - Valor crudo leído de disco o de un patch.
+ * @returns {"cuenta"|"api-key"}
+ */
+function normalizarCredencial(valor) {
+  return CREDENCIALES_VALIDAS.has(valor) ? valor : 'cuenta';
+}
+
+/**
+ * Lee el config del disco y lo mergea con los defaults del schema.
+ *
+ * Tolerante a archivo ausente (proyecto nunca habilitó el ciclo) y a JSON
+ * corrupto (config editado a mano incorrectamente) — en ambos casos cae
+ * a los defaults en vez de lanzar.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {object} Config completo con todos los campos del schema.
+ */
+function leerConfig(baseDir) {
+  const ruta = rutaConfig(baseDir);
+  let crudo = {};
+
+  try {
+    const contenido = fs.readFileSync(ruta, 'utf8');
+    crudo = JSON.parse(contenido);
+  } catch (_) {
+    // Archivo ausente o JSON corrupto: se opera con los defaults.
+    crudo = {};
+  }
+
+  const mergeado = { ...DEFAULTS, ...crudo };
+  mergeado.credencial = normalizarCredencial(mergeado.credencial);
+  return mergeado;
+}
+
+/**
+ * Escribe un patch sobre el config existente (merge, no overwrite) y lo
+ * persiste de forma atómica. Crea `.planning/evolution/` si falta.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {object} patch   - Campos a actualizar; el resto se preserva.
+ * @returns {object} Config final ya escrito a disco.
+ */
+function escribirConfig(baseDir, patch) {
+  const actual = leerConfig(baseDir);
+  const siguiente = { ...actual, ...patch };
+  siguiente.credencial = normalizarCredencial(siguiente.credencial);
+
+  const ruta = rutaConfig(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  atomicWriteJSON(ruta, siguiente);
+  return siguiente;
+}
+
+/**
+ * Predicado de encendido del ciclo autónomo — opt-OUT estricto (decisión
+ * del usuario 2026-07-10): el motor nace ENCENDIDO; se apaga con
+ * `habilitado:false` en el config (`/swl:evolucion-continua off`) o con
+ * `SWL_CICLO_AUTONOMO=0` por sesión. `SWL_CICLO_AUTONOMO=1` fuerza el
+ * encendido por encima de un `off` en disco (override operacional en
+ * CI/cron sin tocar el archivo).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {boolean}
+ */
+function estaHabilitado(baseDir) {
+  if (process.env.SWL_CICLO_AUTONOMO === '0') return false;
+  if (process.env.SWL_CICLO_AUTONOMO === '1') return true;
+  return leerConfig(baseDir).habilitado !== false;
+}
+
+/**
+ * Predicado de encendido de la Fase B (detector + runner headless,
+ * Fase 22) — kill-switch separado del motor general, pero SUBORDINADO a él
+ * (regla de negocio 1: motor apagado ⇒ Fase B apagada, sin excepción). Fase B
+ * no agrega variable de entorno propia: hereda `SWL_CICLO_AUTONOMO` a través
+ * de `estaHabilitado`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {boolean}
+ */
+function estaFaseBHabilitada(baseDir) {
+  if (!estaHabilitado(baseDir)) return false;
+  return leerConfig(baseDir).fase_b_habilitada !== false;
+}
+
+module.exports = {
+  estaHabilitado,
+  estaFaseBHabilitada,
+  leerConfig,
+  escribirConfig,
+};