@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/validar-intent-spec.js

@@ -1,242 +1,242 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: validar-intent-spec.js
- * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit sobre agentes/*.md)
- *
- * Verifica que los agentes con `nivelRiesgo: ALTO` declaren las 6 partes
- * del framework Intent Engineering exigidas por `reglas/intent-engineering.md`:
- *   - strategy (Parte 1)
- *   - healthMetrics (Parte 4)
- *   - steering (Parte 6 — prompt-level)
- *   - hardGuardrails (Parte 6 — orchestration-level)
- *   - fragmentos: [_intent-spec]
- *   - maxTurnos (Parte 8 — Stop Rules)
- *
- * Comportamiento (modo blocking desde ADR-0033):
- *   - BLOQUEA (exit 2) cuando un agente ALTO tiene frontmatter incompleto.
- *     El Write/Edit ya ocurrió (PostToolUse); el exit 2 surface el error a
- *     Claude para que complete el intent spec. Sigue emitiendo el nudge para
- *     trazabilidad antes de bloquear.
- *   - Sale 0 (sin ruido) cuando el agente ALTO está completo o no es ALTO.
- *   - Solo se dispara con archivos `agentes/*.md` (no fragmentos `_*.md`)
- *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/, _userland/
- *
- * Opt-out: SWL_INTENT_SPEC=0 desactiva completamente el hook.
- *
- * Formato del nudge:
- *   {
- *     id: string,
- *     kind: "intent-spec-incomplete",
- *     target: "auto-evolucion-swl",
- *     source: "hooks/validar-intent-spec.js",
- *     message: "...",
- *     data: { archivo, agente, faltan: [...] },
- *     ts: ISO,
- *     accionado: false
- *   }
- *
- * Origen: ADR-0027 (warn-only) → ADR-0033 (promoción a blocking, 2026-06-11).
- * Promoción justificada: 24 días estable en warn-only, 8/8 agentes ALTO con
- * frontmatter completo al momento de la promoción (cero falsos positivos sobre
- * el estado actual). Opt-out preservado: SWL_INTENT_SPEC=0.
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-// ─── Opt-out global ───────────────────────────────────────────────────────
-if (process.env.SWL_INTENT_SPEC === '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 toolName = evento?.tool_name;
-const toolInput = evento?.tool_input;
-
-if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
-  process.exit(0);
-}
-
-const filePath = toolInput?.file_path;
-if (!filePath) {
-  process.exit(0);
-}
-
-const pathNormalized = filePath.replace(/\\/g, '/');
-
-// Solo agentes/*.md (NO fragmentos _*.md)
-if (!/\/agentes\/[^_][^/]*\.md$/.test(pathNormalized)) {
-  process.exit(0);
-}
-
-const RUTAS_EXCLUIDAS = [
-  '/temp/',
-  '/node_modules/',
-  '/respositorios-git/',
-  '/_userland/',
-  '/.planning/',
-];
-if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
-  process.exit(0);
-}
-
-if (!fs.existsSync(filePath)) {
-  process.exit(0);
-}
-
-// ─── Parsear frontmatter YAML ─────────────────────────────────────────────
-let contenido;
-try {
-  contenido = fs.readFileSync(filePath, 'utf-8');
-} catch (_) {
-  process.exit(0);
-}
-
-// Normalizar line endings (CRLF Windows → LF) antes del regex.
-// Sin esto el hook nunca detectaba frontmatter en archivos guardados desde
-// Git for Windows con autocrlf=true (bug reportado 2026-05-18).
-contenido = contenido.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-
-const matchFM = contenido.match(/^---\n([\s\S]+?)\n---/);
-if (!matchFM) {
-  // Sin frontmatter — no es un agente conforme. Otros validadores lo detectan.
-  process.exit(0);
-}
-
-const yamlBlob = matchFM[1];
-
-// Parser mínimo de frontmatter (sin dependencias). Solo lee:
-// - nivelRiesgo: VALOR
-// - presencia de claves de primer nivel
-const lineas = yamlBlob.split('\n');
-const claves = new Set();
-let nivelRiesgo = null;
-let fragmentosTieneIntentSpec = false;
-let dentroDeFragmentos = false;
-
-// Strip inline YAML comments (' # ...' o '\t# ...') y comillas wrapping.
-// Sin esto, `nivelRiesgo: ALTO # ejemplo` se parsearía como "ALTO # ejemplo"
-// y la comparación con 'ALTO' fallaría silenciosamente (bug latente 2026-05-18).
-function limpiarValorYaml(crudo) {
-  let v = crudo;
-  // Comentario inline: '#' precedido de whitespace (no '#' dentro de strings comillados,
-  // que en este parser mínimo no soportamos pero sí intentamos respetar).
-  const m = v.match(/^(.*?)(?:\s+#.*)?$/);
-  if (m) v = m[1];
-  v = v.trim();
-  // Strip comillas wrapping si las hay
-  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
-    v = v.slice(1, -1);
-  }
-  return v;
-}
-
-for (const linea of lineas) {
-  // Detectar clave de primer nivel (sin indent)
-  const m = linea.match(/^([a-zA-Z_][a-zA-Z0-9_]*):/);
-  if (m) {
-    claves.add(m[1]);
-    if (m[1] === 'nivelRiesgo') {
-      const crudo = linea.split(':').slice(1).join(':').trim();
-      nivelRiesgo = limpiarValorYaml(crudo);
-      dentroDeFragmentos = false;
-    } else if (m[1] === 'fragmentos') {
-      dentroDeFragmentos = true;
-      // Caso fragmentos: [_intent-spec] inline
-      if (linea.includes('_intent-spec')) {
-        fragmentosTieneIntentSpec = true;
-      }
-    } else {
-      dentroDeFragmentos = false;
-    }
-  } else if (dentroDeFragmentos && linea.includes('_intent-spec')) {
-    fragmentosTieneIntentSpec = true;
-  }
-}
-
-// Solo evaluar agentes ALTO
-if (nivelRiesgo !== 'ALTO') {
-  process.exit(0);
-}
-
-// Verificar las 6 partes obligatorias
-const CAMPOS_OBLIGATORIOS = ['strategy', 'healthMetrics', 'steering', 'hardGuardrails', 'maxTurnos'];
-const faltan = CAMPOS_OBLIGATORIOS.filter((c) => !claves.has(c));
-
-if (!fragmentosTieneIntentSpec) {
-  faltan.push('fragmentos:[_intent-spec]');
-}
-
-if (faltan.length === 0) {
-  process.exit(0);
-}
-
-// ─── Emitir nudge ─────────────────────────────────────────────────────────
-const CWD = process.cwd();
-const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
-const nombreAgente = path.basename(filePath, '.md');
-
-const nudge = {
-  id: crypto.randomBytes(8).toString('hex'),
-  kind: 'intent-spec-incomplete',
-  target: 'auto-evolucion-swl',
-  source: 'hooks/validar-intent-spec.js',
-  message:
-    `Agente ALTO riesgo ${nombreAgente} no declara intent spec completo. ` +
-    `Faltan: ${faltan.join(', ')}. Cargar Skill("proceso-intent-engineering") + ` +
-    `regla intent-engineering.md y completar frontmatter.`,
-  data: {
-    archivo: rutaRelativa,
-    agente: nombreAgente,
-    nivelRiesgo: 'ALTO',
-    faltan,
-  },
-  ts: new Date().toISOString(),
-  accionado: false,
-};
-
-const nudgesDir = path.join(CWD, '.planning', 'evolution');
-const nudgesFile = path.join(nudgesDir, 'nudges.jsonl');
-
-try {
-  if (!fs.existsSync(nudgesDir)) {
-    fs.mkdirSync(nudgesDir, { recursive: true });
-  }
-  fs.appendFileSync(nudgesFile, JSON.stringify(nudge) + '\n');
-} catch (_) {
-  // Si falla persistir, no romper el flujo del bloqueo
-}
-
-// ─── Modo blocking (ADR-0033) ─────────────────────────────────────────────
-// El agente ALTO tiene frontmatter incompleto: bloquear (exit 2) y surface el
-// detalle a Claude por stderr para que complete el intent spec. Opt-out global
-// SWL_INTENT_SPEC=0 ya cortó arriba; aquí el bloqueo es activo.
-const razon = [
-  `Intent spec incompleto en agente ALTO riesgo: ${nombreAgente}`,
-  `Faltan campos obligatorios: ${faltan.join(', ')}.`,
-  ``,
-  `Completa el frontmatter según reglas/intent-engineering.md:`,
-  `  strategy, healthMetrics, steering, hardGuardrails, maxTurnos,`,
-  `  y fragmentos: [_intent-spec].`,
-  `Carga Skill("proceso-intent-engineering") para la guía completa.`,
-  ``,
-  `Para omitir esta verificación: SWL_INTENT_SPEC=0 (registra la excepción).`,
-].join('\n');
-process.stderr.write(razon);
-process.exit(2);
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: validar-intent-spec.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit sobre agentes/*.md)
+ *
+ * Verifica que los agentes con `nivelRiesgo: ALTO` declaren las 6 partes
+ * del framework Intent Engineering exigidas por `reglas/intent-engineering.md`:
+ *   - strategy (Parte 1)
+ *   - healthMetrics (Parte 4)
+ *   - steering (Parte 6 — prompt-level)
+ *   - hardGuardrails (Parte 6 — orchestration-level)
+ *   - fragmentos: [_intent-spec]
+ *   - maxTurnos (Parte 8 — Stop Rules)
+ *
+ * Comportamiento (modo blocking desde ADR-0033):
+ *   - BLOQUEA (exit 2) cuando un agente ALTO tiene frontmatter incompleto.
+ *     El Write/Edit ya ocurrió (PostToolUse); el exit 2 surface el error a
+ *     Claude para que complete el intent spec. Sigue emitiendo el nudge para
+ *     trazabilidad antes de bloquear.
+ *   - Sale 0 (sin ruido) cuando el agente ALTO está completo o no es ALTO.
+ *   - Solo se dispara con archivos `agentes/*.md` (no fragmentos `_*.md`)
+ *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/, _userland/
+ *
+ * Opt-out: SWL_INTENT_SPEC=0 desactiva completamente el hook.
+ *
+ * Formato del nudge:
+ *   {
+ *     id: string,
+ *     kind: "intent-spec-incomplete",
+ *     target: "auto-evolucion-swl",
+ *     source: "hooks/validar-intent-spec.js",
+ *     message: "...",
+ *     data: { archivo, agente, faltan: [...] },
+ *     ts: ISO,
+ *     accionado: false
+ *   }
+ *
+ * Origen: ADR-0027 (warn-only) → ADR-0033 (promoción a blocking, 2026-06-11).
+ * Promoción justificada: 24 días estable en warn-only, 8/8 agentes ALTO con
+ * frontmatter completo al momento de la promoción (cero falsos positivos sobre
+ * el estado actual). Opt-out preservado: SWL_INTENT_SPEC=0.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ─── Opt-out global ───────────────────────────────────────────────────────
+if (process.env.SWL_INTENT_SPEC === '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 toolName = evento?.tool_name;
+const toolInput = evento?.tool_input;
+
+if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
+
+const filePath = toolInput?.file_path;
+if (!filePath) {
+  process.exit(0);
+}
+
+const pathNormalized = filePath.replace(/\\/g, '/');
+
+// Solo agentes/*.md (NO fragmentos _*.md)
+if (!/\/agentes\/[^_][^/]*\.md$/.test(pathNormalized)) {
+  process.exit(0);
+}
+
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/_userland/',
+  '/.planning/',
+];
+if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
+  process.exit(0);
+}
+
+if (!fs.existsSync(filePath)) {
+  process.exit(0);
+}
+
+// ─── Parsear frontmatter YAML ─────────────────────────────────────────────
+let contenido;
+try {
+  contenido = fs.readFileSync(filePath, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+// Normalizar line endings (CRLF Windows → LF) antes del regex.
+// Sin esto el hook nunca detectaba frontmatter en archivos guardados desde
+// Git for Windows con autocrlf=true (bug reportado 2026-05-18).
+contenido = contenido.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+const matchFM = contenido.match(/^---\n([\s\S]+?)\n---/);
+if (!matchFM) {
+  // Sin frontmatter — no es un agente conforme. Otros validadores lo detectan.
+  process.exit(0);
+}
+
+const yamlBlob = matchFM[1];
+
+// Parser mínimo de frontmatter (sin dependencias). Solo lee:
+// - nivelRiesgo: VALOR
+// - presencia de claves de primer nivel
+const lineas = yamlBlob.split('\n');
+const claves = new Set();
+let nivelRiesgo = null;
+let fragmentosTieneIntentSpec = false;
+let dentroDeFragmentos = false;
+
+// Strip inline YAML comments (' # ...' o '\t# ...') y comillas wrapping.
+// Sin esto, `nivelRiesgo: ALTO # ejemplo` se parsearía como "ALTO # ejemplo"
+// y la comparación con 'ALTO' fallaría silenciosamente (bug latente 2026-05-18).
+function limpiarValorYaml(crudo) {
+  let v = crudo;
+  // Comentario inline: '#' precedido de whitespace (no '#' dentro de strings comillados,
+  // que en este parser mínimo no soportamos pero sí intentamos respetar).
+  const m = v.match(/^(.*?)(?:\s+#.*)?$/);
+  if (m) v = m[1];
+  v = v.trim();
+  // Strip comillas wrapping si las hay
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    v = v.slice(1, -1);
+  }
+  return v;
+}
+
+for (const linea of lineas) {
+  // Detectar clave de primer nivel (sin indent)
+  const m = linea.match(/^([a-zA-Z_][a-zA-Z0-9_]*):/);
+  if (m) {
+    claves.add(m[1]);
+    if (m[1] === 'nivelRiesgo') {
+      const crudo = linea.split(':').slice(1).join(':').trim();
+      nivelRiesgo = limpiarValorYaml(crudo);
+      dentroDeFragmentos = false;
+    } else if (m[1] === 'fragmentos') {
+      dentroDeFragmentos = true;
+      // Caso fragmentos: [_intent-spec] inline
+      if (linea.includes('_intent-spec')) {
+        fragmentosTieneIntentSpec = true;
+      }
+    } else {
+      dentroDeFragmentos = false;
+    }
+  } else if (dentroDeFragmentos && linea.includes('_intent-spec')) {
+    fragmentosTieneIntentSpec = true;
+  }
+}
+
+// Solo evaluar agentes ALTO
+if (nivelRiesgo !== 'ALTO') {
+  process.exit(0);
+}
+
+// Verificar las 6 partes obligatorias
+const CAMPOS_OBLIGATORIOS = ['strategy', 'healthMetrics', 'steering', 'hardGuardrails', 'maxTurnos'];
+const faltan = CAMPOS_OBLIGATORIOS.filter((c) => !claves.has(c));
+
+if (!fragmentosTieneIntentSpec) {
+  faltan.push('fragmentos:[_intent-spec]');
+}
+
+if (faltan.length === 0) {
+  process.exit(0);
+}
+
+// ─── Emitir nudge ─────────────────────────────────────────────────────────
+const CWD = process.cwd();
+const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
+const nombreAgente = path.basename(filePath, '.md');
+
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'intent-spec-incomplete',
+  target: 'auto-evolucion-swl',
+  source: 'hooks/validar-intent-spec.js',
+  message:
+    `Agente ALTO riesgo ${nombreAgente} no declara intent spec completo. ` +
+    `Faltan: ${faltan.join(', ')}. Cargar Skill("proceso-intent-engineering") + ` +
+    `regla intent-engineering.md y completar frontmatter.`,
+  data: {
+    archivo: rutaRelativa,
+    agente: nombreAgente,
+    nivelRiesgo: 'ALTO',
+    faltan,
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+};
+
+const nudgesDir = path.join(CWD, '.planning', 'evolution');
+const nudgesFile = path.join(nudgesDir, 'nudges.jsonl');
+
+try {
+  if (!fs.existsSync(nudgesDir)) {
+    fs.mkdirSync(nudgesDir, { recursive: true });
+  }
+  fs.appendFileSync(nudgesFile, JSON.stringify(nudge) + '\n');
+} catch (_) {
+  // Si falla persistir, no romper el flujo del bloqueo
+}
+
+// ─── Modo blocking (ADR-0033) ─────────────────────────────────────────────
+// El agente ALTO tiene frontmatter incompleto: bloquear (exit 2) y surface el
+// detalle a Claude por stderr para que complete el intent spec. Opt-out global
+// SWL_INTENT_SPEC=0 ya cortó arriba; aquí el bloqueo es activo.
+const razon = [
+  `Intent spec incompleto en agente ALTO riesgo: ${nombreAgente}`,
+  `Faltan campos obligatorios: ${faltan.join(', ')}.`,
+  ``,
+  `Completa el frontmatter según reglas/intent-engineering.md:`,
+  `  strategy, healthMetrics, steering, hardGuardrails, maxTurnos,`,
+  `  y fragmentos: [_intent-spec].`,
+  `Carga Skill("proceso-intent-engineering") para la guía completa.`,
+  ``,
+  `Para omitir esta verificación: SWL_INTENT_SPEC=0 (registra la excepción).`,
+].join('\n');
+process.stderr.write(razon);
+process.exit(2);