@ingeniomaps/cauce 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -14,6 +14,29 @@ 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

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/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, unquoted,
+  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
@@ -250,12 +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, en el entorno del guard: escrita delante '
-      + 'del comando no llega hasta acá.')
-  }
+  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.63.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