@saulwade/swl-ses 1.8.0 → 2.0.0

package/hooks/lib/evolution-tracker.js

@@ -64,6 +64,7 @@ const EXCLUDED_FILENAME_PATTERNS = [
   /\.rej$/,             // patch reject
   /\.merge_file_/,      // merge tools (kdiff3, etc.)
   /~$/,                 // editores tipo Emacs/Vim
+  /\.evolved-diff\.(md|txt)$/, // diffs de merge (no son componentes; .md legacy)
 ];
 
 /**
@@ -407,7 +408,13 @@ const DIFF_NOISY_THRESHOLD = 50;
  *
  * Estrategia: toma el archivo nuevo como base y re-aplica los campos de
  * evolución (frontmatter evolved-*). Las mutaciones de contenido se preservan
- * generando un archivo .evolved-diff.md que Claude puede re-aplicar.
+ * generando un archivo `.evolved-diff.txt` que Claude puede re-aplicar.
+ *
+ * Extensión `.txt` (no `.md`) deliberada: el diff vive junto al componente
+ * evolucionado (incluyendo `commands/`), pero el harness de Claude Code indexa
+ * todo `.md` dentro de `commands/` como slash-command — un `aprender.evolved-diff.md`
+ * aparecería como `/swl:aprender.evolved-diff`. Con `.txt` el harness no lo indexa
+ * y `scanEvolved` (que solo recorre `.md`) tampoco lo confunde con un componente.
  *
  * Comparación: solo el body (post-frontmatter) se compara línea-a-línea.
  * El frontmatter SIEMPRE diverge (el destino tiene campos `evolved-*` que el
@@ -415,7 +422,8 @@ const DIFF_NOISY_THRESHOLD = 50;
  * contarlo como mutación genera ruido por desplazamiento.
  *
  * Limpieza: cuando un merge posterior elimina la divergencia (diffs vacíos),
- * borra el `.evolved-diff.md` huérfano de sesiones previas si existe.
+ * borra el `.evolved-diff.txt` huérfano de sesiones previas si existe (y el
+ * `.evolved-diff.md` legacy de versiones anteriores a esta corrección).
  *
  * Cap defensivo: si tras alinear correctamente el body aún hay más de
  * `DIFF_NOISY_THRESHOLD` líneas distintas, genera un resumen estadístico
@@ -470,7 +478,17 @@ function mergeEvolved(destino, origen, versionNueva) {
       }
     }
 
-    const diffPath = destino.replace(/\.md$/, '.evolved-diff.md');
+    const diffPath = destino.replace(/\.md$/, '.evolved-diff.txt');
+    // Legacy: versiones previas escribían el diff como `.evolved-diff.md`, que
+    // el harness indexaba como slash-command. Se limpia siempre que se toca el
+    // componente, exista o no divergencia nueva.
+    const diffPathLegacy = destino.replace(/\.md$/, '.evolved-diff.md');
+    const limpiarLegacy = () => {
+      if (fs.existsSync(diffPathLegacy)) {
+        try { fs.unlinkSync(diffPathLegacy); return true; } catch { /* best-effort */ }
+      }
+      return false;
+    };
 
     if (diffs.length === 0) {
       // Sin diferencias reales — limpiar diff huérfano si existe (de sesión
@@ -486,6 +504,7 @@ function mergeEvolved(destino, origen, versionNueva) {
           // el merge sigue siendo válido.
         }
       }
+      if (limpiarLegacy()) cleanedDiff = true;
 
       // force: true — `mergeEvolved` solo se invoca en contexto de update
       // intencional. El skip de isPackageRoot() aplica a la primera marca
@@ -557,6 +576,8 @@ function mergeEvolved(destino, origen, versionNueva) {
     ].join('\n');
 
     atomicWriteSync(diffPath, diffContent, 'utf8');
+    // Si existía el `.evolved-diff.md` legacy, eliminarlo: el `.txt` lo reemplaza.
+    limpiarLegacy();
 
     return { merged: true, diffPath, diffsCount: diffs.length, truncated };
   } catch (err) {

package/hooks/lib/loop-telemetry.js

@@ -0,0 +1,321 @@
+'use strict';
+
+/**
+ * Loop Telemetry — Registro tabular de iteraciones para loops autónomos.
+ *
+ * Da trazabilidad a cualquier loop iterativo del sistema (autoresearch,
+ * /swl:verificar --until-converge, /swl:nemesis --remediar): cada corrida
+ * deja una carpeta en .planning/loops/ con un TSV por iteración, un
+ * handoff.json para encadenamiento entre comandos, y utilidades de análisis
+ * de trayectoria (plateau, revert rate, mejora acumulada).
+ *
+ * Patrón adoptado del análisis de autoresearch v2.1 (temp/autoresearch-master,
+ * sesión 2026-06-10): TSV por iteración + handoff.json + detección de plateau.
+ * Adaptado a convenciones SWL: estado en .planning/ (no /tmp), escrituras
+ * atómicas para JSON, append para el TSV (alta frecuencia relativa).
+ *
+ * Formato del TSV (línea 1 = comentario de dirección, línea 2 = header):
+ *
+ *   # metric_direction: higher_is_better
+ *   iteracion	timestamp	metrica	delta	estado	descripcion
+ *   0	2026-06-10T20:00:00Z	62	0	baseline	estado inicial
+ *   1	2026-06-10T20:05:00Z	65	3	keep	agrega test de frontera X
+ *
+ * Estados canónicos: baseline | keep | revert | crash | no-op | error-metrica
+ *
+ * Zero-deps (solo node:fs/path y hooks/lib/atomic-write).
+ *
+ * @module hooks/lib/loop-telemetry
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync, atomicWriteJSON } = require('./atomic-write');
+
+const DIR_LOOPS = path.join('.planning', 'loops');
+const COLUMNAS_DEFAULT = ['iteracion', 'timestamp', 'metrica', 'delta', 'estado', 'descripcion'];
+const DIRECCIONES = ['higher_is_better', 'lower_is_better'];
+const VERSION_HANDOFF = '1.0-swl';
+
+/** Sanitiza un valor para celda TSV: sin tabs ni saltos de línea. */
+function sanitizarCelda(valor) {
+  if (valor === null || valor === undefined) return '';
+  return String(valor).replace(/[\t\r\n]+/g, ' ').trim();
+}
+
+function timestampCompacto(fecha) {
+  const f = fecha || new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    String(f.getFullYear()).slice(2) + pad(f.getMonth() + 1) + pad(f.getDate()) +
+    '-' + pad(f.getHours()) + pad(f.getMinutes()) + pad(f.getSeconds())
+  );
+}
+
+/**
+ * Inicia una corrida de loop: crea .planning/loops/<tipo>-<YYMMDD-HHMMSS>/
+ * con iteraciones.tsv (comentario de dirección + header) y meta.json.
+ *
+ * @param {object} opciones
+ * @param {string} opciones.tipo - Identificador del loop (ej: 'autoresearch', 'nemesis', 'verificar').
+ * @param {string} [opciones.direccion='higher_is_better'] - Dirección de la métrica.
+ * @param {string[]} [opciones.columnas] - Columnas del TSV (default COLUMNAS_DEFAULT).
+ * @param {string} [opciones.raiz=process.cwd()] - Raíz del proyecto.
+ * @param {object} [opciones.config={}] - Config inicial persistida en meta.json.
+ * @returns {{dir: string, tsvPath: string}}
+ */
+function iniciarCorrida({ tipo, direccion = 'higher_is_better', columnas, raiz = process.cwd(), config = {} }) {
+  if (!tipo || !/^[a-z0-9-]+$/.test(tipo)) {
+    throw new TypeError(`loop-telemetry: tipo inválido "${tipo}" — usar kebab-case (ej: "autoresearch")`);
+  }
+  if (!DIRECCIONES.includes(direccion)) {
+    throw new TypeError(`loop-telemetry: dirección inválida "${direccion}" — usar ${DIRECCIONES.join(' | ')}`);
+  }
+  const cols = Array.isArray(columnas) && columnas.length > 0 ? columnas : COLUMNAS_DEFAULT;
+
+  // Colisiones en el mismo segundo: el sufijo se agrega sobre la base
+  // inmutable (tipo-YYMMDD-HHMMSS-N). NUNCA recortar del nombre acumulado —
+  // un replace de "último bloque numérico" se come el HHMMSS del timestamp
+  // y rompe la extracción de tipo en corridaActiva().
+  const base = path.join(raiz, DIR_LOOPS, `${tipo}-${timestampCompacto()}`);
+  let dir = base;
+  let sufijo = 1;
+  while (fs.existsSync(dir)) {
+    sufijo += 1;
+    dir = `${base}-${sufijo}`;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tsvPath = path.join(dir, 'iteraciones.tsv');
+  // Header del TSV con escritura atómica: un header truncado rompe
+  // parsearTsv() para toda la vida de la corrida. Las filas posteriores sí
+  // van con appendFileSync (excepción sancionada para appends).
+  atomicWriteSync(tsvPath, `# metric_direction: ${direccion}\n${cols.join('\t')}\n`);
+
+  atomicWriteJSON(path.join(dir, 'meta.json'), {
+    tipo,
+    direccion,
+    columnas: cols,
+    iniciada: new Date().toISOString(),
+    config,
+  });
+
+  return { dir, tsvPath };
+}
+
+/**
+ * Registra una iteración: agrega una fila al TSV de la corrida.
+ * Las columnas se toman del header del TSV; campos ausentes quedan vacíos.
+ *
+ * @param {string} dir - Directorio de la corrida (retornado por iniciarCorrida).
+ * @param {object} fila - Objeto con valores por columna (ej: {iteracion: 1, metrica: 65, estado: 'keep'}).
+ */
+function registrarIteracion(dir, fila) {
+  const tsvPath = path.join(dir, 'iteraciones.tsv');
+  const { columnas } = parsearTsv(tsvPath);
+  const valores = columnas.map((col) => {
+    if (col === 'timestamp' && !(col in fila)) return new Date().toISOString();
+    return sanitizarCelda(fila[col]);
+  });
+  fs.appendFileSync(tsvPath, valores.join('\t') + '\n', 'utf8');
+}
+
+/** Parsea el TSV de una corrida. @returns {{direccion: string, columnas: string[], filas: object[]}} */
+function parsearTsv(tsvPath) {
+  const contenido = fs.readFileSync(tsvPath, 'utf8');
+  const lineas = contenido.split('\n').filter((l) => l.trim().length > 0);
+
+  let direccion = 'higher_is_better';
+  let inicio = 0;
+  if (lineas[0] && lineas[0].startsWith('#')) {
+    const m = lineas[0].match(/metric_direction:\s*(\S+)/);
+    if (m && DIRECCIONES.includes(m[1])) direccion = m[1];
+    inicio = 1;
+  }
+  const columnas = (lineas[inicio] || '').split('\t');
+  const filas = lineas.slice(inicio + 1).map((linea) => {
+    const celdas = linea.split('\t');
+    const obj = {};
+    columnas.forEach((col, i) => { obj[col] = celdas[i] !== undefined ? celdas[i] : ''; });
+    return obj;
+  });
+  return { direccion, columnas, filas };
+}
+
+/** Lee las iteraciones de una corrida. */
+function leerIteraciones(dir) {
+  return parsearTsv(path.join(dir, 'iteraciones.tsv'));
+}
+
+/**
+ * Detecta plateau: las últimas `ventana` filas con métrica numérica no
+ * muestran mejora respecto al mejor valor previo a la ventana.
+ *
+ * @param {object[]} filas - Filas parseadas del TSV.
+ * @param {object} [opciones]
+ * @param {number} [opciones.ventana=3]
+ * @param {string} [opciones.campo='metrica']
+ * @param {string} [opciones.direccion='higher_is_better']
+ * @returns {boolean}
+ */
+function detectarPlateau(filas, { ventana = 3, campo = 'metrica', direccion = 'higher_is_better' } = {}) {
+  const numericas = filas
+    .map((f) => parseFloat(f[campo]))
+    .filter((n) => Number.isFinite(n));
+  if (numericas.length < ventana + 1) return false;
+
+  const previas = numericas.slice(0, numericas.length - ventana);
+  const ultimas = numericas.slice(-ventana);
+  const mejor = direccion === 'higher_is_better' ? Math.max(...previas) : Math.min(...previas);
+
+  return ultimas.every((n) =>
+    direccion === 'higher_is_better' ? n <= mejor : n >= mejor
+  );
+}
+
+/**
+ * Analiza la trayectoria completa de una corrida.
+ *
+ * @param {string} dir - Directorio de la corrida.
+ * @returns {{
+ *   totalIteraciones: number, keeps: number, reverts: number, crashes: number,
+ *   revertRate: number, metricaInicial: number|null, metricaFinal: number|null,
+ *   mejora: number|null, plateau: boolean, mayorSalto: {iteracion: string, delta: number}|null,
+ *   recomendacion: string
+ * }}
+ */
+function analizarTrayectoria(dir) {
+  const { direccion, filas } = leerIteraciones(dir);
+  const datos = filas.filter((f) => f.estado !== 'baseline');
+  const keeps = datos.filter((f) => f.estado === 'keep').length;
+  const reverts = datos.filter((f) => f.estado === 'revert').length;
+  const crashes = datos.filter((f) => f.estado === 'crash').length;
+  const total = datos.length;
+
+  const metricas = filas
+    .map((f) => parseFloat(f.metrica))
+    .filter((n) => Number.isFinite(n));
+  const metricaInicial = metricas.length > 0 ? metricas[0] : null;
+  const metricaFinal = metricas.length > 0 ? metricas[metricas.length - 1] : null;
+  const mejora = metricaInicial !== null && metricaFinal !== null
+    ? metricaFinal - metricaInicial
+    : null;
+
+  let mayorSalto = null;
+  for (const f of datos) {
+    const delta = parseFloat(f.delta);
+    if (!Number.isFinite(delta)) continue;
+    const magnitud = direccion === 'higher_is_better' ? delta : -delta;
+    if (mayorSalto === null || magnitud > (direccion === 'higher_is_better' ? mayorSalto.delta : -mayorSalto.delta)) {
+      mayorSalto = { iteracion: f.iteracion, delta };
+    }
+  }
+
+  const plateau = detectarPlateau(filas, { direccion });
+  const revertRate = total > 0 ? Math.round((reverts / total) * 100) / 100 : 0;
+
+  let recomendacion;
+  if (plateau) {
+    recomendacion = 'detener: plateau detectado — las últimas iteraciones no mejoran la métrica';
+  } else if (total >= 3 && revertRate >= 0.67) {
+    recomendacion = 'cambiar estrategia: la mayoría de las mutaciones se revierten';
+  } else if (total === 0) {
+    recomendacion = 'sin datos: la corrida no registró iteraciones más allá del baseline';
+  } else {
+    recomendacion = 'continuar: la trayectoria muestra mejora activa';
+  }
+
+  return {
+    totalIteraciones: total, keeps, reverts, crashes, revertRate,
+    metricaInicial, metricaFinal, mejora, plateau, mayorSalto, recomendacion,
+  };
+}
+
+/**
+ * Escribe handoff.json: contrato de encadenamiento entre comandos iterativos.
+ *
+ * @param {string} dir - Directorio de la corrida.
+ * @param {object} datos
+ * @param {string} datos.source - Comando origen (ej: 'swl:nemesis').
+ * @param {string} datos.status - COMPLETO | ACOTADO | PLATEAU | INTERRUMPIDO | ERROR
+ * @param {object[]} [datos.findings=[]] - Hallazgos transferibles ({id, severidad, archivo_linea, resumen}).
+ * @param {object} [datos.config={}] - Config consumible por el comando siguiente.
+ */
+function escribirHandoff(dir, { source, status, findings = [], config = {} }) {
+  if (!source || !status) {
+    throw new TypeError('loop-telemetry: handoff requiere source y status');
+  }
+  atomicWriteJSON(path.join(dir, 'handoff.json'), {
+    version: VERSION_HANDOFF,
+    source,
+    status,
+    timestamp: new Date().toISOString(),
+    iteraciones_tsv: 'iteraciones.tsv',
+    findings,
+    config,
+  });
+}
+
+/** Lee el handoff.json de una corrida. @returns {object|null} */
+function leerHandoff(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'handoff.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Encuentra la corrida activa más reciente: directorio en .planning/loops/
+ * cuyo iteraciones.tsv fue modificado hace menos de maxEdadMin minutos.
+ *
+ * @param {string} [raiz=process.cwd()]
+ * @param {object} [opciones]
+ * @param {number} [opciones.maxEdadMin=30]
+ * @returns {{dir: string, tipo: string, ultimasFilas: object[], totalFilas: number}|null}
+ */
+function corridaActiva(raiz = process.cwd(), { maxEdadMin = 30 } = {}) {
+  const base = path.join(raiz, DIR_LOOPS);
+  let candidatos;
+  try {
+    candidatos = fs.readdirSync(base, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(base, e.name));
+  } catch {
+    return null;
+  }
+
+  const limite = Date.now() - maxEdadMin * 60 * 1000;
+  let mejor = null;
+  for (const dir of candidatos) {
+    const tsvPath = path.join(dir, 'iteraciones.tsv');
+    let stat;
+    try { stat = fs.statSync(tsvPath); } catch { continue; }
+    if (stat.mtimeMs < limite) continue;
+    if (mejor === null || stat.mtimeMs > mejor.mtimeMs) {
+      mejor = { dir, mtimeMs: stat.mtimeMs };
+    }
+  }
+  if (!mejor) return null;
+
+  const { filas } = leerIteraciones(mejor.dir);
+  return {
+    dir: mejor.dir,
+    tipo: path.basename(mejor.dir).replace(/-\d{6}-\d{6}(-\d+)?$/, ''),
+    ultimasFilas: filas.slice(-3),
+    totalFilas: filas.length,
+  };
+}
+
+module.exports = {
+  DIR_LOOPS,
+  COLUMNAS_DEFAULT,
+  iniciarCorrida,
+  registrarIteracion,
+  leerIteraciones,
+  detectarPlateau,
+  analizarTrayectoria,
+  escribirHandoff,
+  leerHandoff,
+  corridaActiva,
+};

package/hooks/notificacion-telegram.js

@@ -3,7 +3,13 @@
 /**
  * Hook de notificaciones Telegram para Claude Code.
  *
- * Se dispara en Stop, Notification y SubagentStop.
+ * Se dispara en Stop y Notification por default. SubagentStop es opt-in:
+ * cuando un turno usa subagentes, SubagentStop dispara casi simultáneo al
+ * Stop final y el usuario recibe el mismo contenido dos veces ("Subagente
+ * terminó" + "Claude terminó"). Para recibir también las terminaciones de
+ * subagentes (útil con agentes largos en background):
+ *   CLAUDE_NOTIFY_EVENTS=Stop,Notification,SubagentStop
+ *
  * Best-effort: siempre termina con exit 0, nunca bloquea el flujo de Claude.
  * Registra actividad en ~/.claude/notifications/hook.log (append-only).
  *
@@ -214,9 +220,11 @@ async function run() {
 
   log('evento', nombreEvento, 'proyecto', nombreProyecto);
 
-  // Filtrar eventos no deseados (configurable vía variable de entorno)
+  // Filtrar eventos no deseados (configurable vía variable de entorno).
+  // SubagentStop NO está en el default: duplica la notificación del Stop
+  // final cuando el turno usó subagentes (mismo cuerpo, dos mensajes).
   const eventosActivos = (
-    process.env.CLAUDE_NOTIFY_EVENTS || 'Stop,Notification,SubagentStop'
+    process.env.CLAUDE_NOTIFY_EVENTS || 'Stop,Notification'
   ).split(',').map(s => s.trim());
 
   if (!eventosActivos.includes(nombreEvento)) {

package/hooks/spec-gate.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: spec-gate.js  (Gate G0 — SDD)
+ * Tipo: PreToolUse  (matcher: Write|Edit|MultiEdit)
+ *
+ * Detecta escrituras de CÓDIGO FUENTE sin fase activa con PLAN aprobado.
+ * Implementa el gate G0 del flujo SPEC→PLAN→TEST→CODE→VERIFY (Revisión
+ * Evolutiva 03 §5.2): "ningún Write/Edit a código fuente sin fase activa
+ * con PLAN aprobado".
+ *
+ * Modo actual: WARN-ONLY (ADR-0034, decisión D-07 de 10-CONTEXTO.md).
+ *   - Emite nudge `kind: spec-gate` a .planning/evolution/nudges.jsonl.
+ *   - NUNCA exit 2. La promoción a blocking se decide vía ADR tras ~2
+ *     semanas de calibración sin falsos positivos (patrón ADR-0027→0033).
+ *
+ * Concepto "fase activa": `.planning/locks/fase-activa.json`, escrito por
+ * /swl:aprobar-plan al firmar un plan y eliminado por /swl:ejecutar-fase al
+ * cerrar la fase. Formato:
+ *   { numero, planPath, sha256, aprobadoEn, aprobadoPor }
+ * El hook re-computa el SHA256 del plan referenciado y lo compara con el del
+ * archivo de fase activa — verificación autocontenida (sin dependencia de
+ * scripts/lib/, que puede no estar distribuido en proyectos destino).
+ *
+ * Zero-config: en proyectos sin `.planning/` el hook sale 0 sin ruido.
+ * Opt-out: SWL_SPEC_GATE=0 desactiva completamente el hook.
+ *
+ * Modelo de amenaza (heredado de plan-lock.js): detecta omisión accidental
+ * del ciclo GSD y mutación post-firma; NO resiste a un adversario con
+ * escritura al repo (puede regenerar fase-activa.json).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/_userland/',
+  '/.planning/',
+  '/.claude/',
+];
+
+/**
+ * Clasificador de código fuente. Reutiliza esArchivoFuente() de
+ * calidad-pre-commit.js (misma definición que el gate G3) con fallback
+ * defensivo si el módulo no está disponible en el destino.
+ */
+function cargarClasificador() {
+  try {
+    const calidad = require(path.join(__dirname, 'calidad-pre-commit.js'));
+    if (typeof calidad.esArchivoFuente === 'function') return calidad.esArchivoFuente;
+  } catch (_) {
+    // Fallback mínimo: extensiones de código de los lenguajes soportados,
+    // excluyendo tests por sufijo/directorio.
+  }
+  return function esArchivoFuenteFallback(ruta) {
+    const normal = ruta.replace(/\\/g, '/');
+    if (/\.(test|spec)\.[jt]sx?$/.test(normal)) return false;
+    if (/(^|\/)(tests?|__tests__|spec)\//.test(normal)) return false;
+    if (/\.(md|json|ya?ml|toml|ini|cfg|conf|txt|svg|lock)$/i.test(normal)) return false;
+    return /\.(jsx?|tsx?|py|go|rs|java|kt|cs|rb|php|swift|c|cc|cpp|h|hpp)$/i.test(normal);
+  };
+}
+
+/**
+ * Evalúa el estado de la fase activa del proyecto en `cwd`.
+ * @returns {{ ok: boolean, motivo: string|null, numero?: number }}
+ *   ok=true  → hay fase activa con plan íntegro (no advertir)
+ *   ok=false → motivo describe por qué no hay cobertura de spec
+ */
+function evaluarFaseActiva(cwd) {
+  const rutaFaseActiva = path.join(cwd, '.planning', 'locks', 'fase-activa.json');
+  if (!fs.existsSync(rutaFaseActiva)) {
+    return { ok: false, motivo: 'sin fase activa (no existe .planning/locks/fase-activa.json)' };
+  }
+
+  let faseActiva;
+  try {
+    faseActiva = JSON.parse(fs.readFileSync(rutaFaseActiva, 'utf-8'));
+  } catch (_) {
+    return { ok: false, motivo: 'fase-activa.json corrupto (JSON inválido)' };
+  }
+
+  if (!faseActiva || typeof faseActiva.planPath !== 'string' || typeof faseActiva.sha256 !== 'string') {
+    return { ok: false, motivo: 'fase-activa.json sin planPath/sha256' };
+  }
+
+  const planAbs = path.isAbsolute(faseActiva.planPath)
+    ? faseActiva.planPath
+    : path.join(cwd, faseActiva.planPath);
+
+  if (!fs.existsSync(planAbs)) {
+    return { ok: false, motivo: `el plan de la fase activa no existe (${faseActiva.planPath})` };
+  }
+
+  let hashActual;
+  try {
+    hashActual = crypto.createHash('sha256').update(fs.readFileSync(planAbs)).digest('hex');
+  } catch (_) {
+    return { ok: false, motivo: 'no se pudo leer el plan de la fase activa' };
+  }
+
+  if (hashActual !== faseActiva.sha256) {
+    return {
+      ok: false,
+      motivo: `el plan de la fase activa fue mutado tras la firma (${faseActiva.planPath})`,
+      numero: faseActiva.numero,
+    };
+  }
+
+  return { ok: true, motivo: null, numero: faseActiva.numero };
+}
+
+/**
+ * Decide si la escritura amerita advertencia G0.
+ * @returns {null | { motivo: string }}  null = silencio
+ */
+function evaluarEscritura({ cwd, toolName, filePath, esArchivoFuente }) {
+  if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) return null;
+  if (!filePath) return null;
+
+  // Zero-config: sin .planning/ no hay ciclo GSD que vigilar.
+  if (!fs.existsSync(path.join(cwd, '.planning'))) return null;
+
+  const normal = filePath.replace(/\\/g, '/');
+  if (RUTAS_EXCLUIDAS.some((ex) => normal.includes(ex))) return null;
+  if (!esArchivoFuente(normal)) return null;
+
+  const fase = evaluarFaseActiva(cwd);
+  if (fase.ok) return null;
+
+  return { motivo: fase.motivo };
+}
+
+function emitirNudge({ cwd, filePath, motivo }) {
+  const rutaRelativa = path.relative(cwd, filePath).replace(/\\/g, '/');
+  let emit;
+  try {
+    ({ emit } = require(path.join(__dirname, 'lib', 'nudge-tracker.js')));
+  } catch (_) {
+    return;
+  }
+  try {
+    emit({
+      kind: 'spec-gate',
+      target: rutaRelativa,
+      source: 'hooks/spec-gate.js',
+      message:
+        `Gate G0 (warn): escritura de código fuente ${rutaRelativa} ${motivo}. ` +
+        `El flujo SDD espera una fase activa con PLAN aprobado (/swl:aprobar-plan N) ` +
+        `antes de escribir código. Si es un fix trivial o exploración, ignora este aviso ` +
+        `— se usa para calibrar la promoción a blocking (ADR-0034). Opt-out: SWL_SPEC_GATE=0.`,
+      data: { archivo: rutaRelativa, motivo, gate: 'G0' },
+      mutation_category: 'optimize',
+      risk_level: 'low',
+    });
+  } catch (_) {
+    // La observabilidad nunca bloquea el trabajo productivo.
+  }
+}
+
+function main() {
+  if (process.env.SWL_SPEC_GATE === '0') process.exit(0);
+
+  let hookInput = '';
+  try {
+    hookInput = fs.readFileSync(0, 'utf-8');
+  } catch (_) {
+    process.exit(0);
+  }
+
+  let evento;
+  try {
+    evento = JSON.parse(hookInput);
+  } catch (_) {
+    process.exit(0);
+  }
+
+  const cwd = process.cwd();
+  const toolName = evento?.tool_name;
+  const filePath = evento?.tool_input?.file_path;
+
+  let resultado = null;
+  try {
+    resultado = evaluarEscritura({
+      cwd,
+      toolName,
+      filePath,
+      esArchivoFuente: cargarClasificador(),
+    });
+  } catch (_) {
+    process.exit(0);
+  }
+
+  if (resultado) {
+    emitirNudge({ cwd, filePath, motivo: resultado.motivo });
+  }
+
+  // WARN-ONLY (ADR-0034): jamás exit 2 en este modo.
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { evaluarFaseActiva, evaluarEscritura, RUTAS_EXCLUIDAS };