@ingeniomaps/cauce 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -14,6 +14,65 @@ 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.64.0] - 2026-09-06
+
+### Agregado
+
+- **Las salidas de los guards están documentadas, y con su alcance real.** Cinco guards se pueden abrir
+  y ninguna de las cinco llaves estaba escrita en un archivo que alguien fuera a abrir: el bloqueo te
+  nombraba una variable y no había dónde leer dónde va. `AGENTS.md` ahora las lista en «Qué se puede
+  editar y qué no», con lo incómodo dicho: el guard lee la variable de **su propio proceso**, así que
+  escribirla delante del comando no llega, y la forma que sí funciona —exportarla en el entorno desde
+  el que arranca tu runner— deja el guard apagado hasta que cierres la sesión. La única con alcance de
+  operación es la aprobación de gobernanza.
+
+- **Un commit de gobernanza se aprueba por operación, no por sesión.** El guard ofrecía como salida
+  `OPS_GOVERNANCE_OVERRIDE=1`, que se lee del entorno del proceso: prendida antes de lanzar tu runner
+  deja el guard apagado hasta que la sesión cierre. Eso convierte «aprobado este commit» en «apagado
+  hasta que me vaya», y el `Makefile` de este proyecto ya decía cuál es el alcance correcto — «la
+  autorización de R10 es por operación y humana». **Qué cambia para vos**: escribís las rutas
+  autorizadas en `planning/.governance-approval`, una por línea, y el commit pasa. Vale para ese
+  conjunto y para ningún otro: si después sumás un archivo, ese archivo no está aprobado. No se consume
+  ni se borra sola —así un commit frenado por otra razón no te obliga a rehacerla—, así que `check` te
+  avisa mientras exista para que la borres. La variable sigue funcionando y el mensaje del guard ahora
+  dice por qué no es la vía recomendada.
+
+## [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/cli/planning.js

@@ -11,6 +11,7 @@ const PC = require('../planning/contracts')
 const SZ = require('../planning/sizing')
 const ST = require('../planning/state')
 const AD = require('../planning/adoption')
+const AP = require('../hooks/approval')
 const I = require('../integrations/registry')
 const O = require('../core/ownership')
 const OB = require('../core/onboarding')
@@ -85,6 +86,14 @@ function check(dir, cli) {
     epics, milestones, done, wip, roles, humanActions: P.readHumanActions(root), adopted: new Set(adopted),
   }))
   warnings.push(...AD.report({ done, epics, adopted }))
+  // Una aprobación de gobernanza vale para el conjunto que nombra, así que olvidada sigue autorizando
+  // esas mismas rutas la próxima vez que alguien las stagee. No caduca sola: lo que la cierra es que se
+  // vea en cada corrida y alguien la borre.
+  const aprobadas = AP.read(path.resolve(root, '..'))
+  if (aprobadas.length) {
+    warnings.push(`planning/${AP.APPROVAL}: ${aprobadas.length} ruta(s) de gobernanza aprobadas y sin `
+      + 'borrar; el archivo sigue autorizándolas')
+  }
 
   const integration = I.validate(path.resolve(root, '..'))
   errors.push(...integration.errors)

package/engine/hooks/approval.js

@@ -0,0 +1,31 @@
+'use strict'
+
+// La aprobación de un commit de gobernanza: una lista de rutas que una persona escribió a mano para
+// autorizar exactamente ese cambio. Existe porque la vía que había era una variable de entorno, y una
+// variable es por sesión: prendida antes de lanzar el runner deja el guard apagado hasta que la sesión
+// cierre. El `Makefile` de este repositorio ya dice cuál es el alcance correcto —«la autorización de R10
+// es por operación y humana»—, y una llave que dura toda la sesión no lo es.
+//
+// **Se coteja, no se consume.** Borrar el archivo al leerlo daría el mismo alcance y traería dos cosas
+// que no queremos: hoy ningún guard escribe en el repositorio, y `governance` corre antes que `verify`,
+// así que un commit frenado por otra razón se habría llevado puesta la aprobación y habría que
+// rehacerla. Cotejando, la aprobación vale para el conjunto que nombra y para ningún otro: en cuanto
+// cambia lo que está en el índice deja de servir, que es «por operación» sin fecha ni contador.
+//
+// Queda a la vista porque `check` avisa mientras exista. Sin eso, un archivo olvidado sigue autorizando
+// esas mismas rutas la próxima vez que alguien las stagee, que es la puerta abierta que esto evitaba.
+
+const path = require('node:path')
+const fs = require('node:fs')
+
+const APPROVAL = '.governance-approval'
+
+// Una ruta por línea, `#` para lo demás. El archivo ausente y el vacío son lo mismo: no hay nada
+// aprobado, que es el estado normal.
+function read(root) {
+  let text = ''
+  try { text = fs.readFileSync(path.join(root, 'planning', APPROVAL), 'utf8') } catch { return [] }
+  return text.split('\n').map((line) => line.replace(/#.*$/, '').trim()).filter(Boolean)
+}
+
+module.exports = { APPROVAL, read }

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,8 +10,9 @@ 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, findOpsRoot,
 } = require('./input')
+const AP = require('./approval')
 
 // Dónde empieza y dónde termina una palabra dentro de un comando. Tres reglas de la tabla de abajo lo
 // decidían por su cuenta admitiendo sólo un espacio, el principio o el fin, y en un shell una palabra
@@ -169,10 +170,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 +188,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.
@@ -247,11 +251,19 @@ function governance(input) {
       String.raw`|evaluations\/(?:cases\/|expected-behaviors\.yaml)|learning\/proposals\/))`,
   )
   const governed = stagedFiles(dir).filter((file) => governedPattern.test(file))
-  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.')
-  }
+  if (!governed.length) return
+  // La aprobación vale para lo que nombra y para nada más: lo que quede sin cubrir es lo que se
+  // reporta. Así una aprobación vieja no autoriza el archivo que se sumó después, que es la diferencia
+  // entre una llave por operación y una puerta que quedó abierta.
+  const root = findOpsRoot(process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || cwdOf(input))
+  const aprobados = new Set(root ? AP.read(root) : [])
+  const pendientes = governed.filter((file) => !aprobados.has(file))
+  if (!pendientes.length) return
+  const files = pendientes.map((file) => `  - ${file}`).join('\n')
+  block(`El commit toca gobernanza protegida:\n${files}\n`
+    + `Aprobalo escribiendo esas rutas en planning/${AP.APPROVAL}, una por línea: vale para ese `
+    + 'conjunto y deja de valer en cuanto cambie. La variable OPS_GOVERNANCE_OVERRIDE=1 sigue '
+    + 'existiendo y apaga el guard para toda la sesión, que es por lo que no es la vía recomendada.')
 }
 
 function run(program, args, cwd) {

package/package.json

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

package/template/AGENTS.md

@@ -98,6 +98,34 @@ siquiera están acá — los lee el motor desde el paquete.
 Un guard existente **no se edita**: `upgrade` detecta el cambio y se detiene antes de pisarlo, y con
 `--force` deja registrado qué descartó.
 
+### Cuando un guard te frena con razón
+
+Algunos bloqueos tienen salida, y conviene saber cuál antes de necesitarla — el momento en que un guard
+te frena es el peor para elegir bien.
+
+**Un commit que toca gobernanza** —reglas, ADRs, el contrato de un cargo o lo que lo mide— se autoriza
+escribiendo las rutas en `planning/.governance-approval`, una por línea, con `#` para lo que no sea una
+ruta. Vale para ese conjunto y para ningún otro: si después sumás un archivo, ese archivo no está
+aprobado y el guard lo nombra. No se borra sola —así un commit frenado por otra cosa no te obliga a
+rehacerla—, así que `check` te avisa mientras exista, y borrarla es parte de terminar.
+
+**Las demás salidas son variables de entorno**, y hay que decir su alcance
+porque no es el que uno espera: el guard la lee de **su propio proceso**, no del comando. Escribirla
+delante —`VAR=1 git commit`— no llega. La forma que sí funciona es exportarla en el entorno desde el que
+arranca tu runner, y eso deja el guard apagado **hasta que cierres la sesión**, no para un comando.
+
+| variable | qué abre |
+|---|---|
+| `OPS_GOVERNANCE_OVERRIDE=1` | lo mismo que la aprobación de arriba, pero para toda la sesión |
+| `OPS_MIGRATIONS_OVERRIDE=1` | escribir SQL destructivo en una migración |
+| `OPS_TEST_EVIDENCE_OVERRIDE=1` | borrar o apagar una prueba |
+| `OPS_DEPENDENCIES_OVERRIDE=1` | tocar manifiestos y lockfiles, publicar o instalar global |
+| `OPS_SKIP_VERIFY=1` | saltear los gates del stack antes de un commit |
+
+Son de sesión y no de operación, que es exactamente lo que la aprobación de gobernanza vino a corregir.
+Mientras sigan así, lo que corresponde es prenderlas para lo que hacía falta y apagarlas después — y que
+la razón quede escrita donde alguien la lea, no sólo en la memoria de quien la prendió.
+
 ## Cómo leer el estado
 
 Antes de abrir un archivo de `planning/`, preguntarle al CLI: es determinista, no gasta contexto y no