@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/lib/plan-lock.js

@@ -1,275 +1,275 @@
-'use strict';
-
-/**
- * plan-lock.js — Firma y verificación de integridad de PLAN.md (Gate G1).
- *
- * Materializa el gate G1 del enforcement SDD (Fase 09, ADR de la Revisión
- * Evolutiva 03): un PLAN aprobado vía `/swl:aprobar-plan` queda firmado con
- * un SHA256 escrito en `.planning/locks/<basename>.lock`. `ejecutar-fase`
- * recomputa ese hash al arrancar; un plan mutado tras la aprobación detiene
- * la ejecución. Cierra el hueco "el plan puede mutar tras aprobación" que
- * dejaba SDD en ~60%.
- *
- * Cláusula de gracia D-05 (compatibilidad legacy): un PLAN con
- * `estado: aprobado` en su frontmatter pero SIN `.lock` correspondiente
- * (los planes creados antes de la Fase 09) se considera `modo: "legacy"` y
- * se ejecuta con advertencia, sin bloqueo. Solo los planes firmados vía
- * `/swl:aprobar-plan` (post-Fase 09) exigen coincidencia de hash.
- *
- * MODELO DE AMENAZA (gate G1): el lock detecta MUTACIÓN ACCIDENTAL o no
- * aprobada del PLAN tras su firma, y planes alterados por un agente que
- * confabula. NO es un control criptográfico contra un adversario con acceso
- * de escritura al repo — quien pueda commitear puede recalcular el SHA256 y
- * re-firmar. La evidencia real de aprobación es `aprobadoPor:` + el commit del
- * lock por `/swl:aprobar-plan` en el audit trail de git. El SHA256 solo detecta
- * drift entre firma y verificación. (Verificación Fase 09, hallazgo S-6.)
- *
- * API:
- *   firmarPlan(planPath, opciones?)  -> { ok, sha256, lockPath, archivo }
- *   verificarPlan(planPath)          -> { ok, modo, motivo, ... }
- *   resolverLockPath(planPath)       -> string (ruta del .lock esperado)
- *
- * Zero-dependencies. Compatible Windows (hash sobre buffer crudo). Node 18+.
- *
- * Origen: Fase 09 — enforcement SDD/TDD vNext H1, Slice 1.
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo idéntico
-// al de scripts/generar-skills-lock.js para no acoplar a un layout fijo.
-let atomicWriteSync;
-try {
-  ({ atomicWriteSync } = require(path.join(__dirname, '..', '..', 'hooks', 'lib', 'atomic-write.js')));
-} catch {
-  atomicWriteSync = (p, c, e) => {
-    const dir = path.dirname(p);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(p, c, e);
-  };
-}
-
-const LOCK_VERSION = 1;
-
-// Basename válido de un PLAN de fase: `PLAN.md` o `0N-PLAN.md`. Evita que
-// `firmarPlan` produzca locks de archivos arbitrarios (falsearía el audit
-// trail de aprobación). Verificación Fase 09, hallazgo S-2.
-const PLAN_BASENAME_RE = /^(\d{2}-)?PLAN\.md$/;
-
-/**
- * SHA256 de un buffer. Idéntico a scripts/generar-skills-lock.js:42-44.
- * Se hashea el buffer crudo (no string utf8) para que el hash sea byte-exacto
- * y detecte incluso cambios de fin de línea introducidos por un editor.
- *
- * @param {Buffer|string} data
- * @returns {string} hex digest
- */
-function sha256(data) {
-  return crypto.createHash('sha256').update(data).digest('hex');
-}
-
-/**
- * Extrae el campo `estado:` del frontmatter YAML del PLAN.
- * Reutiliza el patrón CRLF-safe de scripts/generar-skills-lock.js:46-55.
- *
- * @param {string} contenido
- * @returns {string|null} valor de `estado` o null si no hay frontmatter/campo
- */
-function leerEstado(contenido) {
-  const m = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
-  if (!m) return null;
-  for (const linea of m[1].split(/\r?\n/)) {
-    const kv = linea.match(/^estado:\s*(.*)$/);
-    if (kv) return kv[1].trim();
-  }
-  return null;
-}
-
-/**
- * Resuelve el directorio `.planning/locks/` ascendiendo desde el PLAN hasta
- * encontrar el directorio `.planning` ancestro. Robusto ante planes en
- * `.planning/fases/0N-PLAN.md` o `.planning/PLAN.md`.
- *
- * Hardening S-1 (verificación Fase 09):
- *   - Resuelve symlinks con `fs.realpathSync` antes de ascender, para que un
- *     symlink plantado (`temp/.planning` → `/etc/.planning`) no permita escapar
- *     del árbol real del proyecto.
- *   - SIN fallback ciego: si no hay `.planning` ancestro, retorna `null` (antes
- *     escribía `locks/` al lado del PLAN, en ubicación arbitraria). El caller
- *     trata `null` como error explícito.
- *
- * @param {string} planPath
- * @returns {string|null} ruta absoluta del directorio de locks, o null si no
- *   hay `.planning` ancestro.
- */
-function resolverLocksDir(planPath) {
-  let dir;
-  try {
-    dir = path.dirname(fs.realpathSync(path.resolve(planPath)));
-  } catch {
-    dir = path.dirname(path.resolve(planPath));
-  }
-  while (dir !== path.dirname(dir)) {
-    if (path.basename(dir) === '.planning') {
-      return path.join(dir, 'locks');
-    }
-    dir = path.dirname(dir);
-  }
-  return null;
-}
-
-/**
- * Ruta del `.lock` esperado para un PLAN dado.
- *
- * @param {string} planPath
- * @returns {string|null} ruta absoluta del archivo `.lock`, o null si el PLAN
- *   no tiene un `.planning` ancestro.
- */
-function resolverLockPath(planPath) {
-  const dir = resolverLocksDir(planPath);
-  return dir ? path.join(dir, `${path.basename(planPath)}.lock`) : null;
-}
-
-/**
- * Firma un PLAN: computa su SHA256 y escribe el `.lock` correspondiente.
- * Idempotente — re-firmar sobreescribe el lock (caso re-aprobación).
- *
- * @param {string} planPath
- * @param {object} [opciones]
- * @param {string} [opciones.firmadoPor='swl:aprobar-plan']
- * @param {string} [opciones.firmadoEn] ISO timestamp; default new Date()
- * @returns {{ok: boolean, sha256?: string, lockPath?: string, archivo?: string, motivo?: string}}
- */
-function firmarPlan(planPath, opciones = {}) {
-  if (!fs.existsSync(planPath)) {
-    return { ok: false, motivo: `PLAN no existe: ${planPath}` };
-  }
-  const archivo = path.basename(planPath);
-  if (!PLAN_BASENAME_RE.test(archivo)) {
-    return {
-      ok: false,
-      motivo: `basename inválido para firma: "${archivo}". Solo se firman PLAN.md o 0N-PLAN.md de fases.`,
-    };
-  }
-  const lockPath = resolverLockPath(planPath);
-  if (!lockPath) {
-    return {
-      ok: false,
-      motivo: `el PLAN no tiene un directorio .planning ancestro: ${planPath}`,
-    };
-  }
-  const buffer = fs.readFileSync(planPath);
-  const hash = sha256(buffer);
-
-  const lock = {
-    version: LOCK_VERSION,
-    archivo,
-    sha256: hash,
-    firmadoEn: opciones.firmadoEn || new Date().toISOString(),
-    firmadoPor: opciones.firmadoPor || 'swl:aprobar-plan',
-  };
-
-  atomicWriteSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
-  return { ok: true, sha256: hash, lockPath, archivo };
-}
-
-/**
- * Verifica la integridad de un PLAN contra su `.lock`.
- *
- * Modos de retorno:
- *   - `firmado`     : existe lock y el hash coincide  -> ok: true
- *   - `legacy`      : NO existe lock pero estado:aprobado (gracia D-05) -> ok: true
- *   - `mutado`      : existe lock y el hash NO coincide -> ok: false
- *   - `lock-corrupto`: el lock existe pero no es JSON válido -> ok: false
- *   - `sin-firmar`  : NO existe lock y estado != aprobado -> ok: false
- *   - `sin-planning`: el PLAN no tiene `.planning` ancestro -> ok: false
- *   - `no-existe`   : el PLAN no existe en disco -> ok: false
- *
- * @param {string} planPath
- * @returns {{ok: boolean, modo: string, motivo?: string, hashEsperado?: string, hashActual?: string, lockPath?: string}}
- */
-function verificarPlan(planPath) {
-  if (!fs.existsSync(planPath)) {
-    return { ok: false, modo: 'no-existe', motivo: `PLAN no existe: ${planPath}` };
-  }
-  const lockPath = resolverLockPath(planPath);
-  if (!lockPath) {
-    return {
-      ok: false,
-      modo: 'sin-planning',
-      motivo: `el PLAN no tiene un directorio .planning ancestro: ${planPath}`,
-    };
-  }
-  const buffer = fs.readFileSync(planPath);
-  const hashActual = sha256(buffer);
-
-  if (!fs.existsSync(lockPath)) {
-    // Cláusula de gracia D-05: plan aprobado antes de que existiera el lock.
-    const estado = leerEstado(buffer.toString('utf8'));
-    if (estado === 'aprobado') {
-      return {
-        ok: true,
-        modo: 'legacy',
-        motivo: 'plan aprobado pre-Fase09 (sin lock); ejecutar con advertencia',
-        hashActual,
-        lockPath,
-      };
-    }
-    return {
-      ok: false,
-      modo: 'sin-firmar',
-      motivo: `plan sin aprobar y sin lock (estado: ${estado || 'ausente'})`,
-      hashActual,
-      lockPath,
-    };
-  }
-
-  let lock;
-  try {
-    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
-  } catch (err) {
-    return {
-      ok: false,
-      modo: 'lock-corrupto',
-      motivo: `lock malformado en ${lockPath}: ${err.message}`,
-      hashActual,
-      lockPath,
-    };
-  }
-
-  const hashEsperado = lock && typeof lock.sha256 === 'string' ? lock.sha256 : null;
-  if (!hashEsperado) {
-    return {
-      ok: false,
-      modo: 'lock-corrupto',
-      motivo: `lock sin campo sha256 en ${lockPath}`,
-      hashActual,
-      lockPath,
-    };
-  }
-
-  if (hashEsperado === hashActual) {
-    return { ok: true, modo: 'firmado', hashEsperado, hashActual, lockPath };
-  }
-
-  return {
-    ok: false,
-    modo: 'mutado',
-    motivo: 'plan mutado tras aprobación (el hash no coincide con el lock)',
-    hashEsperado,
-    hashActual,
-    lockPath,
-  };
-}
-
-module.exports = {
-  firmarPlan,
-  verificarPlan,
-  resolverLockPath,
-  resolverLocksDir,
-  sha256,
-  leerEstado,
-  LOCK_VERSION,
-};
+'use strict';
+
+/**
+ * plan-lock.js — Firma y verificación de integridad de PLAN.md (Gate G1).
+ *
+ * Materializa el gate G1 del enforcement SDD (Fase 09, ADR de la Revisión
+ * Evolutiva 03): un PLAN aprobado vía `/swl:aprobar-plan` queda firmado con
+ * un SHA256 escrito en `.planning/locks/<basename>.lock`. `ejecutar-fase`
+ * recomputa ese hash al arrancar; un plan mutado tras la aprobación detiene
+ * la ejecución. Cierra el hueco "el plan puede mutar tras aprobación" que
+ * dejaba SDD en ~60%.
+ *
+ * Cláusula de gracia D-05 (compatibilidad legacy): un PLAN con
+ * `estado: aprobado` en su frontmatter pero SIN `.lock` correspondiente
+ * (los planes creados antes de la Fase 09) se considera `modo: "legacy"` y
+ * se ejecuta con advertencia, sin bloqueo. Solo los planes firmados vía
+ * `/swl:aprobar-plan` (post-Fase 09) exigen coincidencia de hash.
+ *
+ * MODELO DE AMENAZA (gate G1): el lock detecta MUTACIÓN ACCIDENTAL o no
+ * aprobada del PLAN tras su firma, y planes alterados por un agente que
+ * confabula. NO es un control criptográfico contra un adversario con acceso
+ * de escritura al repo — quien pueda commitear puede recalcular el SHA256 y
+ * re-firmar. La evidencia real de aprobación es `aprobadoPor:` + el commit del
+ * lock por `/swl:aprobar-plan` en el audit trail de git. El SHA256 solo detecta
+ * drift entre firma y verificación. (Verificación Fase 09, hallazgo S-6.)
+ *
+ * API:
+ *   firmarPlan(planPath, opciones?)  -> { ok, sha256, lockPath, archivo }
+ *   verificarPlan(planPath)          -> { ok, modo, motivo, ... }
+ *   resolverLockPath(planPath)       -> string (ruta del .lock esperado)
+ *
+ * Zero-dependencies. Compatible Windows (hash sobre buffer crudo). Node 18+.
+ *
+ * Origen: Fase 09 — enforcement SDD/TDD vNext H1, Slice 1.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo idéntico
+// al de scripts/generar-skills-lock.js para no acoplar a un layout fijo.
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require(path.join(__dirname, '..', '..', 'hooks', 'lib', 'atomic-write.js')));
+} catch {
+  atomicWriteSync = (p, c, e) => {
+    const dir = path.dirname(p);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, c, e);
+  };
+}
+
+const LOCK_VERSION = 1;
+
+// Basename válido de un PLAN de fase: `PLAN.md` o `0N-PLAN.md`. Evita que
+// `firmarPlan` produzca locks de archivos arbitrarios (falsearía el audit
+// trail de aprobación). Verificación Fase 09, hallazgo S-2.
+const PLAN_BASENAME_RE = /^(\d{2}-)?PLAN\.md$/;
+
+/**
+ * SHA256 de un buffer. Idéntico a scripts/generar-skills-lock.js:42-44.
+ * Se hashea el buffer crudo (no string utf8) para que el hash sea byte-exacto
+ * y detecte incluso cambios de fin de línea introducidos por un editor.
+ *
+ * @param {Buffer|string} data
+ * @returns {string} hex digest
+ */
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Extrae el campo `estado:` del frontmatter YAML del PLAN.
+ * Reutiliza el patrón CRLF-safe de scripts/generar-skills-lock.js:46-55.
+ *
+ * @param {string} contenido
+ * @returns {string|null} valor de `estado` o null si no hay frontmatter/campo
+ */
+function leerEstado(contenido) {
+  const m = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!m) return null;
+  for (const linea of m[1].split(/\r?\n/)) {
+    const kv = linea.match(/^estado:\s*(.*)$/);
+    if (kv) return kv[1].trim();
+  }
+  return null;
+}
+
+/**
+ * Resuelve el directorio `.planning/locks/` ascendiendo desde el PLAN hasta
+ * encontrar el directorio `.planning` ancestro. Robusto ante planes en
+ * `.planning/fases/0N-PLAN.md` o `.planning/PLAN.md`.
+ *
+ * Hardening S-1 (verificación Fase 09):
+ *   - Resuelve symlinks con `fs.realpathSync` antes de ascender, para que un
+ *     symlink plantado (`temp/.planning` → `/etc/.planning`) no permita escapar
+ *     del árbol real del proyecto.
+ *   - SIN fallback ciego: si no hay `.planning` ancestro, retorna `null` (antes
+ *     escribía `locks/` al lado del PLAN, en ubicación arbitraria). El caller
+ *     trata `null` como error explícito.
+ *
+ * @param {string} planPath
+ * @returns {string|null} ruta absoluta del directorio de locks, o null si no
+ *   hay `.planning` ancestro.
+ */
+function resolverLocksDir(planPath) {
+  let dir;
+  try {
+    dir = path.dirname(fs.realpathSync(path.resolve(planPath)));
+  } catch {
+    dir = path.dirname(path.resolve(planPath));
+  }
+  while (dir !== path.dirname(dir)) {
+    if (path.basename(dir) === '.planning') {
+      return path.join(dir, 'locks');
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Ruta del `.lock` esperado para un PLAN dado.
+ *
+ * @param {string} planPath
+ * @returns {string|null} ruta absoluta del archivo `.lock`, o null si el PLAN
+ *   no tiene un `.planning` ancestro.
+ */
+function resolverLockPath(planPath) {
+  const dir = resolverLocksDir(planPath);
+  return dir ? path.join(dir, `${path.basename(planPath)}.lock`) : null;
+}
+
+/**
+ * Firma un PLAN: computa su SHA256 y escribe el `.lock` correspondiente.
+ * Idempotente — re-firmar sobreescribe el lock (caso re-aprobación).
+ *
+ * @param {string} planPath
+ * @param {object} [opciones]
+ * @param {string} [opciones.firmadoPor='swl:aprobar-plan']
+ * @param {string} [opciones.firmadoEn] ISO timestamp; default new Date()
+ * @returns {{ok: boolean, sha256?: string, lockPath?: string, archivo?: string, motivo?: string}}
+ */
+function firmarPlan(planPath, opciones = {}) {
+  if (!fs.existsSync(planPath)) {
+    return { ok: false, motivo: `PLAN no existe: ${planPath}` };
+  }
+  const archivo = path.basename(planPath);
+  if (!PLAN_BASENAME_RE.test(archivo)) {
+    return {
+      ok: false,
+      motivo: `basename inválido para firma: "${archivo}". Solo se firman PLAN.md o 0N-PLAN.md de fases.`,
+    };
+  }
+  const lockPath = resolverLockPath(planPath);
+  if (!lockPath) {
+    return {
+      ok: false,
+      motivo: `el PLAN no tiene un directorio .planning ancestro: ${planPath}`,
+    };
+  }
+  const buffer = fs.readFileSync(planPath);
+  const hash = sha256(buffer);
+
+  const lock = {
+    version: LOCK_VERSION,
+    archivo,
+    sha256: hash,
+    firmadoEn: opciones.firmadoEn || new Date().toISOString(),
+    firmadoPor: opciones.firmadoPor || 'swl:aprobar-plan',
+  };
+
+  atomicWriteSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+  return { ok: true, sha256: hash, lockPath, archivo };
+}
+
+/**
+ * Verifica la integridad de un PLAN contra su `.lock`.
+ *
+ * Modos de retorno:
+ *   - `firmado`     : existe lock y el hash coincide  -> ok: true
+ *   - `legacy`      : NO existe lock pero estado:aprobado (gracia D-05) -> ok: true
+ *   - `mutado`      : existe lock y el hash NO coincide -> ok: false
+ *   - `lock-corrupto`: el lock existe pero no es JSON válido -> ok: false
+ *   - `sin-firmar`  : NO existe lock y estado != aprobado -> ok: false
+ *   - `sin-planning`: el PLAN no tiene `.planning` ancestro -> ok: false
+ *   - `no-existe`   : el PLAN no existe en disco -> ok: false
+ *
+ * @param {string} planPath
+ * @returns {{ok: boolean, modo: string, motivo?: string, hashEsperado?: string, hashActual?: string, lockPath?: string}}
+ */
+function verificarPlan(planPath) {
+  if (!fs.existsSync(planPath)) {
+    return { ok: false, modo: 'no-existe', motivo: `PLAN no existe: ${planPath}` };
+  }
+  const lockPath = resolverLockPath(planPath);
+  if (!lockPath) {
+    return {
+      ok: false,
+      modo: 'sin-planning',
+      motivo: `el PLAN no tiene un directorio .planning ancestro: ${planPath}`,
+    };
+  }
+  const buffer = fs.readFileSync(planPath);
+  const hashActual = sha256(buffer);
+
+  if (!fs.existsSync(lockPath)) {
+    // Cláusula de gracia D-05: plan aprobado antes de que existiera el lock.
+    const estado = leerEstado(buffer.toString('utf8'));
+    if (estado === 'aprobado') {
+      return {
+        ok: true,
+        modo: 'legacy',
+        motivo: 'plan aprobado pre-Fase09 (sin lock); ejecutar con advertencia',
+        hashActual,
+        lockPath,
+      };
+    }
+    return {
+      ok: false,
+      modo: 'sin-firmar',
+      motivo: `plan sin aprobar y sin lock (estado: ${estado || 'ausente'})`,
+      hashActual,
+      lockPath,
+    };
+  }
+
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch (err) {
+    return {
+      ok: false,
+      modo: 'lock-corrupto',
+      motivo: `lock malformado en ${lockPath}: ${err.message}`,
+      hashActual,
+      lockPath,
+    };
+  }
+
+  const hashEsperado = lock && typeof lock.sha256 === 'string' ? lock.sha256 : null;
+  if (!hashEsperado) {
+    return {
+      ok: false,
+      modo: 'lock-corrupto',
+      motivo: `lock sin campo sha256 en ${lockPath}`,
+      hashActual,
+      lockPath,
+    };
+  }
+
+  if (hashEsperado === hashActual) {
+    return { ok: true, modo: 'firmado', hashEsperado, hashActual, lockPath };
+  }
+
+  return {
+    ok: false,
+    modo: 'mutado',
+    motivo: 'plan mutado tras aprobación (el hash no coincide con el lock)',
+    hashEsperado,
+    hashActual,
+    lockPath,
+  };
+}
+
+module.exports = {
+  firmarPlan,
+  verificarPlan,
+  resolverLockPath,
+  resolverLocksDir,
+  sha256,
+  leerEstado,
+  LOCK_VERSION,
+};