@ingeniomaps/cauce 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -14,6 +14,42 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
 diseño — eso vive en el commit y en el código.
 
+## [0.63.0] - 2026-09-06
+
+### Corregido
+
+- **El salto de línea termina la lista de argumentos de un comando.** `shell-boundary` leía los
+  argumentos de un `cp`, un `tee` o un `sed -i` cruzando a la línea siguiente, así que el destino que
+  acusaba podía ser el comando de abajo: un bloqueo que hablaba de una escritura en `…/python3`, una
+  ruta que no aparecía en el comando. Falla hacia el lado seguro —frena de más— pero señala algo que no
+  existe, y un guard que señala mal es el que se termina apagando. **Qué cambia para vos**: si escribís
+  scripts de varias líneas en un solo comando, dejás de ver bloqueos por rutas inventadas; lo que sí
+  escribe fuera de las raíces se sigue frenando igual.
+
+- **El cuerpo de un heredoc es texto, no un comando.** Escribir un archivo con
+  `cat > nota.md <<'FIN' … FIN` juzgaba cada línea del documento como si fuera a ejecutarse, así que no
+  se podía documentar lo que los guards vigilan: un párrafo que explica por qué no se borra la raíz se
+  bloqueaba por nombrarlo, y la salida era cambiar de herramienta para escribir un archivo. Un heredoc
+  es entrada estándar y no se ejecuta nunca. **Qué cambia para vos**: el cuerpo deja de juzgarse y la
+  línea que lo abre se sigue juzgando entera, con su redirección —también si la escribís después del
+  delimitador, como en `cat <<FIN > salida`—. Lo que se pierde a cambio: un cuerpo que después alguien
+  ejecuta; al escribirse no ejecuta nada, y cuando se corra el guard verá el comando de verdad.
+
+- **Una variable delante de `git commit` ya no apaga tres guards.** `dependencies`, `governance` y el
+  control de generados de `verify` sólo corren sobre un commit, y decidían si lo era con un ancla que
+  no contempla lo que un shell admite antes del verbo. Con `VAR=1 git commit` dejaban de correr **sin
+  decir nada**, y con la ironía de que el prefijo que se escribe para un commit de gobernanza es una
+  asignación: `OPS_GOVERNANCE_OVERRIDE=1 git commit` no leía el override, hacía que el guard no se
+  ejecutara. **Qué cambia para vos**: si venías escribiendo ese prefijo, ahora el guard corre y te va a
+  frenar. La variable se lee del entorno del guard, no del comando, y el mensaje ahora lo dice.
+
+- **Un índice que no se puede leer deja de autorizar el commit.** `stagedFiles` devolvía una lista vacía
+  tanto si el índice estaba vacío como si no se pudo leer, y los tres guards de arriba leen esa
+  respuesta: una lectura fallida se les presentaba como «no hay nada que revisar». Llegar a una es
+  fácil, porque el guard no expande variables: `git -C $OPS commit` resuelve la ruta literal `$OPS`.
+  **Qué cambia para vos**: ese comando ahora se frena con un mensaje que nombra la causa. Escribí la
+  ruta literal en `git -C`.
+
 ## [0.62.0] - 2026-09-06
 
 ### Corregido

package/engine/cli/catalog.js

@@ -102,7 +102,15 @@ function evaluationBench(root, agent, caso, force, kind) {
   // reintentos, rehacer un banco es una operación que falla de vez en cuando y deja la corrida sin
   // empezar.
   fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 })
-  IN.scaffold(dir, { name: 'Banco de evaluación', mode: 'sidecar', quiet: true })
+  // Con `force`: el banco es desechable y se acaba de borrar, así que lo que sobreviva al `rmSync` se
+  // pisa en vez de cortar la corrida. Sin esto, `copyTemplate` se niega ante cualquier archivo que
+  // quede —«El destino contiene …/AGENTS.md»— y el mismo test falló así tres veces en un día, en las
+  // dos patas de la matriz. Por qué algo sobrevive a un borrado que no lanzó no está establecido.
+  //
+  // No ablanda ninguna protección: la pregunta «¿acá alguien trabajó?» la contesta el `git status` de
+  // arriba, que exige `--force` explícito para seguir. Esta segunda puerta no la eligió nadie y sólo
+  // se cerraba a veces, que es la clase de freno que enseña a re-correr sin leer.
+  IN.scaffold(dir, { name: 'Banco de evaluación', mode: 'sidecar', quiet: true, force: true })
   // El motor por symlink: la misma resolución que en una instancia real —`node_modules/@ingeniomaps`—
   // sin pagar un `npm install` por corrida. El cargo llega a un banco donde el CLI funciona.
   const scope = path.join(dir, 'node_modules', '@ingeniomaps')

package/engine/hooks/input.js

@@ -22,10 +22,27 @@ function readInput() {
   }
 }
 
+// El cuerpo de un heredoc es entrada estándar: no se ejecuta, se escribe. Juzgarlo como comando frenaba
+// documentar lo que los guards vigilan — escribir un archivo que explica por qué borrar la raíz es
+// catastrófico se bloqueaba por nombrarlo—, y la salida era cambiar de herramienta, que es el rodeo que
+// un guard no debería enseñar.
+//
+// La línea de apertura se conserva **entera**, porque sí es comando y `shell-boundary` tiene que seguir
+// viendo dónde escribe. Entera incluye lo que va después del delimitador: `cat <<FIN > salida` es una
+// forma válida y su destino está ahí. El cuerpo empieza en el salto de línea, no en el delimitador —
+// recortar desde el delimitador se llevaba esa redirección, y nada lo notaba porque en la forma común
+// el destino va antes del `<<`.
+//
+// Lo que se pierde: un cuerpo que después alguien ejecuta. `cat > script.sh <<EOF` no ejecuta nada al
+// escribirse y el guard verá el comando de verdad cuando alguien corra el script; el borde filoso es
+// `$(cat <<EOF …)`, donde el cuerpo sí corre y ya no se mira. Es el mismo trato que con el mensaje de un
+// commit: se frena la forma habitual, no al que quiere pasar.
+const HEREDOC = /<<(-?)\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\2([^\n]*)\n[\s\S]*?^\s*\3\s*$/gm
+
 function commandOf(input) {
   const value = input.tool_input && (input.tool_input.command || input.tool_input.cmd)
     || input.command || input.input && input.input.command || process.env.OPS_HOOK_COMMAND || ''
-  return Array.isArray(value) ? value.join(' ') : String(value)
+  return String(Array.isArray(value) ? value.join(' ') : value).replace(HEREDOC, '<<$1$2$3$2$4')
 }
 
 function fileOf(input) {
@@ -86,19 +103,59 @@ function configOf(root) {
   }
 }
 
+// Vacía lo que va entre comillas, dejando una marca que ningún patrón confunde con una ruta ni con un
+// comando. Vive acá porque la usan tres lugares por razones distintas, y cada uno explica la suya donde
+// la llama.
+const unquoted = (command) => String(command).replace(/'[^']*'|"[^"]*"/g, '\u0000')
+
+// Sobre qué repositorio se lee el índice. En un commit se mira el comando con el mensaje vaciado, por
+// la misma razón por la que `destructive` lo hace: un mensaje que menciona `git -C $VAR` no está
+// eligiendo un repositorio, lo está citando. Sin esto, el commit que explica este arreglo se bloquea a
+// sí mismo — pasó al escribirlo.
+//
+// El precio es una ruta entrecomillada en el propio `-C` de un commit —`git -C "mi carpeta" commit`—,
+// que se pierde y cae al cwd. Es más raro que un mensaje que cita un comando, y el cwd de un commit
+// suele ser el repositorio correcto; el caso contrario deja al guard leyendo un índice ajeno.
 function gitDirectory(command, cwd) {
-  const flag = command.match(/(?:^|\s)git\s+-C\s+(['"]?)([^\s'";&|]+)\1/)
-  const cd = command.match(/(?:^|[;&|]\s*)cd\s+(['"]?)([^\s'";&|]+)\1/)
+  const text = isCommit(command) ? unquoted(command) : command
+  const flag = text.match(/(?:^|\s)git\s+-C\s+(['"]?)([^\s'";&|]+)\1/)
+  const cd = text.match(/(?:^|[;&|]\s*)cd\s+(['"]?)([^\s'";&|]+)\1/)
   return path.resolve(cwd, flag ? flag[2] : cd ? cd[2] : '.')
 }
 
+// Lo que un shell admite delante del verbo: asignaciones de entorno, `env` y `sudo`. `VAR=1 git commit`
+// empieza por la asignación, así que un ancla que sólo acepta el principio del comando o un separador
+// no ve el `git` que viene después.
+//
+// Falla en los dos sentidos y uno no avisa. Del lado ruidoso, el mensaje del commit vuelve a juzgarse
+// como comando. Del silencioso —el que importa— los tres guards que sólo corren sobre un commit dejan
+// de correr: gobernanza, dependencias y generados. Cualquier variable delante alcanza, y la ironía es
+// que el prefijo que el procedimiento manda escribir para un commit de gobernanza es
+// `OPS_GOVERNANCE_OVERRIDE=1`: escrito ahí, el guard no lee el override, directamente no se ejecuta.
+const PREFIX = String.raw`(?:^|[;&|]\s*)(?:(?:env|sudo)\s+)*`
+  + String.raw`(?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)\s+)*`
+const COMMIT = new RegExp(PREFIX + String.raw`git(?:\s+-C\s+\S+)?\s+commit(?:\s|$)`)
+
 function isCommit(command) {
-  return /(?:^|[;&|]\s*)git(?:\s+-C\s+\S+)?\s+commit(?:\s|$)/.test(command)
+  return COMMIT.test(command)
 }
 
+// Un índice vacío y un índice ilegible no son la misma respuesta: la primera autoriza a seguir, la
+// segunda no autoriza nada. Devolviendo `[]` en los dos casos, los tres guards que preguntan acá se
+// apagaban en silencio ante cualquier lectura fallida — y llegar a una es fácil, porque `gitDirectory`
+// no expande variables: `git -C $OPS commit` resuelve la ruta literal `$OPS`, que no existe.
+//
+// Es la regla que el propio shim ya tiene escrita —«Un guard que no encuentra su motor bloquea, nunca
+// permite»—, aplicada donde faltaba. Bloquear desde acá es seguro: los tres llamadores son guards, así
+// que no hay ningún consumidor que sólo quiera consultar el índice.
 function stagedFiles(dir) {
   const result = spawnSync('git', ['-C', dir, 'diff', '--cached', '--name-only'], { encoding: 'utf8' })
-  return result.status === 0 ? result.stdout.trim().split('\n').filter(Boolean) : []
+  if (result.status !== 0) {
+    const why = (result.stderr || '').trim() || (result.error && result.error.message) || 'git falló'
+    block(`no se pudo leer el índice de ${dir} (${why}). Un guard que no puede verificar no autoriza. `
+      + 'Si usaste una variable en `git -C`, escribí la ruta literal.')
+  }
+  return result.stdout.trim().split('\n').filter(Boolean)
 }
 
 // R10 pide «la autorización configurada para el proyecto» y `runner.allowPush` es esa configuración:
@@ -157,5 +214,5 @@ const DECLARE_IT = 'Si el proyecto necesita escribir ahí, declaralo en writable
 module.exports = {
   readInput, commandOf, patchOf, filesOf, contentOf, cwdOf, block, configOf,
   gitDirectory, isCommit, stagedFiles, pushAllowed, findOpsRoot,
-  writableRoots, outsideRoots, DECLARE_IT,
+  writableRoots, outsideRoots, DECLARE_IT, unquoted,
 }

package/engine/hooks/shell.js

@@ -10,7 +10,7 @@ const path = require('node:path')
 const { spawnSync } = require('node:child_process')
 const {
   commandOf, cwdOf, block, gitDirectory, isCommit, stagedFiles, pushAllowed,
-  writableRoots, outsideRoots, DECLARE_IT,
+  writableRoots, outsideRoots, DECLARE_IT, unquoted,
 } = require('./input')
 
 // Dónde empieza y dónde termina una palabra dentro de un comando. Tres reglas de la tabla de abajo lo
@@ -169,10 +169,17 @@ function dependencies(input) {
 // Tres familias, porque los comandos no nombran su destino igual: `tee` y `truncate` escriben en cada
 // argumento, `cp` y sus hermanos en el último, y `sed` sólo escribe con `-i` —sin él lee y manda a
 // stdout, y esa redirección la ve REDIRECT—.
+//
+// El salto de línea termina una lista de argumentos igual que `;`. Sin excluirlo, la de un `cp` seguía
+// leyendo la línea de abajo y el destino terminaba siendo el comando siguiente: un bloqueo que nombraba
+// `…/python3`, una ruta que no aparecía en el comando. Se veía con un heredoc debajo, pero el heredoc no
+// era la causa —sólo hacía que la lectura frenara en un token que sobrevive—: sin él la lista cruzaba
+// igual y el último token era la marca de lo entrecomillado, que el filtro final descarta. O sea que
+// pasaba de casualidad, y aserciar que pasa no fijaba nada.
 const REDIRECT = /(?:^|[\s(])&?\d*>>?\s*(?![&(])([^\s;|&<>()]+)/g
-const EVERY_ARG = /(?:^|[\s;|&(])(tee|truncate)\s+([^;|&<>()]+)/g
-const LAST_ARG = /(?:^|[\s;|&(])(cp|mv|install|rsync)\s+([^;|&<>()]+)/g
-const SED = /(?:^|[\s;|&(])sed\s+([^;|&<>()]+)/g
+const EVERY_ARG = /(?:^|[\s;|&(])(tee|truncate)\s+([^;|&<>()\n]+)/g
+const LAST_ARG = /(?:^|[\s;|&(])(cp|mv|install|rsync)\s+([^;|&<>()\n]+)/g
+const SED = /(?:^|[\s;|&(])sed\s+([^;|&<>()\n]+)/g
 const IN_PLACE = /(?:^|\s)-{1,2}i/
 
 // Los argumentos que no son flags. El valor de un flag se cuela —`truncate -s 0 log` trae el `0`— y no
@@ -180,10 +187,6 @@ const IN_PLACE = /(?:^|\s)-{1,2}i/
 // decide un bloqueo. Filtrarlo sería una rama que ninguna prueba puede ver caer.
 const positional = (text) => text.trim().split(/\s+/).filter((one) => one && !one.startsWith('-'))
 
-// Vacía lo que va entre comillas, dejando una marca que ningún patrón confunde con una ruta ni con un
-// comando. Lo usan dos guards por razones distintas, y cada uno explica la suya donde lo llama.
-const unquoted = (command) => String(command).replace(/'[^']*'|"[^"]*"/g, '\u0000')
-
 // Un `>` adentro de una cadena no redirige nada. Pierde el destino entrecomillado, que es un falso
 // negativo — el error barato en un guard que ya es incompleto, porque el caro es frenar un comando
 // legítimo y que alguien apague el guard entero.
@@ -250,7 +253,8 @@ function governance(input) {
   if (governed.length) {
     const files = governed.map((file) => `  - ${file}`).join('\n')
     block(`El commit toca gobernanza protegida:\n${files}\n` +
-      'Usa OPS_GOVERNANCE_OVERRIDE=1 solo con aprobación.')
+      'Usa OPS_GOVERNANCE_OVERRIDE=1 solo con aprobación, en el entorno del guard: escrita delante '
+      + 'del comando no llega hasta acá.')
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "keywords": [
     "planning",