@ingeniomaps/cauce 0.79.0 → 0.80.0

package/CHANGELOG.md

@@ -14,6 +14,89 @@ 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.80.0] - 2026-09-10
+
+### Agregado
+
+- **Leer una credencial también se frena, y las identidades declaradas cuentan como credencial.** Un guard
+  nuevo, `secrets-read`, corre en la herramienta de lectura de Claude (`Read`) y de Gemini (`read_file`) y
+  frena los mismos archivos que `secrets` frena al escribir. Esos archivos ahora incluyen las identidades
+  `source: file` de `organization/secrets.json`, que antes pasaban por no tener nombre de credencial. En
+  Claude, además, la instalación agrega reglas `permissions.deny` `Read(...)` que el propio Claude aplica
+  también a `cat`, `head`, `tail`, `sed` y redirecciones.
+
+  **Qué cambia para vos**: el agente deja de poder leer `.env`, claves y tokens conocidos; `.env.example`
+  sigue legible. Si una lectura hace falta, aprobá la ruta en `planning/.ops-approval`. Corré
+  `automation install` para que tu `.claude/settings.json` reciba las reglas: se suman a las tuyas. No es un
+  límite de seguridad —un `grep -r` o un script propio siguen leyendo—, y en Codex y Antigravity no hay guard
+  de lectura.
+
+- **Un proveedor de integraciones propio, sin tocar Cauce.** El registro de `integrations/config.json`
+  ya tenía un campo `adapter` que nadie leía: ahora `"adapter": "./adapter.js"` carga el adaptador de la
+  empresa desde `integrations/<nombre>/`, e `integration enable` lo conecta sin exigir un molde de Cauce.
+  El adaptador declara `contract: 1` y las tres funciones del contrato, y `check` rechaza el que no
+  cumpla.
+
+  **Qué cambia para vos**: nada si sólo usás Jira. Para otra herramienta, `integrations/README.md` de tu
+  instancia trae el recorrido.
+
+- **Un contrato de secretos compartido entre repositorios, y un chequeo sin red.** Si tus servicios
+  usan un gestor de secretos, los scripts y workflows que lo conectan terminan copiados en cada
+  repositorio, y el arreglo que alguien hizo en uno no llega a los demás. `organization/secrets.json`
+  declara qué cuenta, qué identidad y qué archivos comparte cada servicio, y
+  `node tools/ops.js secrets check .` compara cada copia contra la canónica que guarda la instancia:
+  dice cuál quedó atrás y el `cp` que la pone al día. También falla si una credencial vive dentro de un
+  repositorio o si la declaración guarda un valor en vez de una referencia.
+
+  **Qué cambia para vos**: nada si no lo usás. Para adoptarlo, `organization/README.md` trae el formato
+  y el recorrido. Cauce no se conecta a ningún gestor ni trae adaptadores: lo que habla con el gestor
+  sigue siendo tuyo. Si tus proyectos tienen instancias separadas, el chequeo sólo compara dentro de
+  cada una: para que un esqueleto y sus derivados se midan contra lo mismo, van como raíces de la misma
+  instancia.
+
+### Corregido
+
+- **`init` rechaza un runner mal escrito sin crear la instancia.** Con `--runner none` —el valor es
+  `ninguno`— o una `--integration` que no existe, `init` escribía la instancia entera y recién después
+  salía con error: el código de salida decía que no había pasado nada y el segundo intento encontraba la
+  carpeta creada. Ahora valida los dos valores antes de escribir.
+
+  **Qué cambia para vos**: nada con un valor correcto. Con uno mal escrito, el destino queda como estaba.
+
+- **El bloqueo de `verify` cita la prueba que falló.** Mostraba la primera línea de la salida que dijera
+  «error», y en un reporte de pruebas ésa puede ser una verde cuyo nombre lo dice. Ahora, con la salida de
+  `node --test` —spec y TAP— y de `go test`, cita la primera prueba en rojo; con otras herramientas sigue
+  buscando por palabra, pero ya no elige una línea marcada como verde.
+
+  **Qué cambia para vos**: el mensaje apunta a la prueba que hay que mirar.
+
+- **Cada bloqueo con salida angosta dice qué líneas pegar.** Aprobar en `planning/.ops-approval` sólo
+  funciona si la ruta está escrita en la forma que ese guard coteja —absoluta la de un `Write`, relativa
+  al repositorio la de un commit—, y el mensaje decía «escribí esa(s) ruta(s)» sin nombrarlas. `verify`
+  y `dependencies` ni siquiera mostraban la línea. Ahora cada bloqueo imprime las líneas exactas, y
+  pegarlas tal cual destraba ese mismo bloqueo.
+
+  **Qué cambia para vos**: si una aprobación no pegaba y terminabas exportando la variable del guard,
+  pegá lo que dice el mensaje.
+
+- **`plan-first` deja de frenar la configuración y los archivos de la instancia.** Frenaba
+  `ops.config.json` —justo el archivo que el límite de raíces manda a editar para declarar una ruta— y,
+  en sidecar, también `AGENTS.md`, `CLAUDE.md`, `package.json` y `.gitignore` de la instancia, como si
+  fueran producto. Ahora producto es el código de una raíz declarada: la instancia sidecar no lo es
+  aunque viva dentro de su raíz (`..`), y lo que queda fuera de toda raíz —lo declarado en
+  `writableOutsideRoots`— tampoco. En embedded, el `package.json` de la raíz sigue siendo producto.
+
+  **Qué cambia para vos**: si aprobabas esas rutas a mano en `.ops-approval` o exportabas
+  `OPS_PLAN_FIRST_OVERRIDE` para poder tocarlas, ya no hace falta.
+
+- **`verify` deja afuera del índice de su copia lo que enlaza.** Cuando el árbol difiere del índice, el
+  guard corre los gates sobre una copia del índice con lo ignorado enlazado —`node_modules`, `.env`—. Si
+  tu `.gitignore` escribe ese directorio con barra final (`node_modules/`), el enlace entraba al índice de
+  la copia, y un gate que recorre lo trackeado —`git ls-files`— lo recibía como si fuera parte del commit.
+
+  **Qué cambia para vos**: si una suite que pasa a mano fallaba bajo `verify` sólo cuando tenías archivos
+  sin trackear, podía ser esto.
+
 ## [0.79.0] - 2026-09-10
 
 ### Corregido

package/README.md

@@ -216,6 +216,7 @@ Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contr
 | `ops integration rebase <ops-root> jira KEY` | Recalcula el borrador canónico sin avanzar la base remota. |
 | `ops integration reconcile <ops-root> jira KEY` | Conserva curación sobre la nueva base remota. |
 | `ops integration writeback-plan <ops-root> jira` | Muestra escrituras posibles sin ejecutarlas. |
+| `ops secrets check <ops-root>` | Compara el contrato de secretos compartido contra cada servicio, sin conectarse. |
 | `ops automation list <ops-root>` | Lista adaptadores y su instalación. |
 | `ops automation list-hooks <ops-root>` | Describe los guards portables disponibles. |
 | `ops automation check <ops-root>` | Valida guards, permisos y configuraciones. |
@@ -314,9 +315,11 @@ La sincronización solo lee Jira. `writeback-plan` calcula intención local, no
 `writeBack` permanece en `false`. Consulta el [recorrido de Jira](template/integrations/jira/README.md) antes
 de conectar una instancia real.
 
-Para añadir otra herramienta se crea un adaptador en `engine/integrations/providers/` con `validateConfig`,
-`fetchItems` y `normalizeFixture`, y se registra en `engine/integrations/registry.js`. Staging, revisión,
-promoción y validación no se reimplementan. Consulta [integrations/README.md](integrations/README.md).
+Para añadir otra herramienta no hace falta tocar Cauce: el adaptador se escribe en la instancia, se
+registra con una ruta en el campo `adapter` y cumple el contrato —`contract: 1`, `validateConfig`,
+`fetchItems` y `normalizeFixture`—. Staging, revisión, promoción y validación no se reimplementan. El
+recorrido está en [template/integrations/README.md](template/integrations/README.md) y el contrato en
+[integrations/README.md](integrations/README.md).
 
 ## Hooks y runners
 

package/automatization/hooks/README.md

@@ -4,6 +4,7 @@ Los hooks convierten invariantes comprobables en gates mecánicos. La base recom
 
 - comandos destructivos, force, amend y stage indiscriminado;
 - escritura de secretos o credenciales;
+- lectura de credenciales conocidas o declaradas, en los runners que tienen una herramienta de lectura;
 - edición manual de código generado y drift respecto a OpenAPI/SQL;
 - commits sin Verify aplicable;
 - apagado o borrado de la prueba que juzga el cambio;
@@ -44,6 +45,20 @@ publica— por la sensación de que ya está cubierto.
 Regla práctica: si algo **tiene** que ser imposible, no lo pongas acá. Ponelo donde no dependa de leer
 una cadena — permisos del runner, alcance del token, aprobación de un PR.
 
+### Leer una credencial
+
+`secrets-read` frena leer, con la herramienta de lectura del runner, un archivo que `secrets` frenaría al
+escribir —los nombres conocidos y las identidades que declara `organization/secrets.json`—. Qué alcanza en
+cada runner es distinto, y conviene saberlo:
+
+- **Claude Code**: el guard corre en `Read`, y además la instalación agrega reglas `permissions.deny`
+  `Read(...)` por los nombres conocidos. Esas reglas las aplica el propio Claude Code a `Read`, a `cat`,
+  `head`, `tail`, `sed` y a las redirecciones, pero no a un `grep -r` ni a un subproceso que abra el archivo
+  por su cuenta. Van por nombre exacto: `.env.*` también negaría `.env.example`.
+- **Gemini CLI**: el guard corre en `read_file`. Un `cat` por `run_shell_command` no lo ve.
+- **Codex y Antigravity**: sin guard de lectura. Sus adaptadores sólo enganchan shell y edición, y leer por
+  shell no pasa por ningún matcher de archivo.
+
 ## Cómo se ejecutan
 
 ```text
@@ -67,8 +82,9 @@ runner, mientras la lógica se prueba y mantiene una sola vez en `engine/hooks/r
 
 | Grupo | Guards | Wrapper |
 |---|---|---|
-| `pre-shell` | destructive, git-add, dependencies, governance, verify | `guard-shell.sh` |
-| `pre-files` | secrets, generated, workspace-boundary, engine, migrations, integration-snapshot, test-evidence | `guard-files.sh` |
+| `pre-shell` | destructive, git-add, dependencies, governance, verify, shell-boundary | `guard-shell.sh` |
+| `pre-files` | secrets, generated, workspace-boundary, engine, migrations, integration-snapshot, test-evidence, plan-first | `guard-files.sh` |
+| `pre-read` | secrets-read | `guard-secrets-read.sh` |
 | `stop` | planning-drift | `guard-planning-drift.sh` |
 
 Registrar el grupo gasta un proceso por herramienta en lugar de cinco, con el mismo orden y la misma

package/automatization/hooks/guard-secrets-read.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Shim: qué bloquea el guard está en engine/hooks/run.js → guards['secrets-read'].
+exec "$(dirname "$0")/run-hook.sh" secrets-read

package/automatization/runners/claude/README.md

@@ -6,7 +6,9 @@ Adaptador nativo mediante `PreToolUse` y `Stop`. Instalar con:
 node tools/ops.js automation install . claude
 ```
 
-El instalador fusiona la sección `hooks` en `.claude/settings.json` y conserva otras claves. Si ya
+El instalador fusiona la sección `hooks` en `.claude/settings.json` y conserva otras claves. También
+suma a `permissions.deny` reglas `Read(...)` por los nombres de credencial conocidos, junto a las que el
+proyecto ya tenga; una que Cauce retire en una versión futura no se quita sola. Si ya
 existe una versión distinta de un archivo, se detiene sin sobrescribirla para no destruir
 personalizaciones del proyecto. También crea `CLAUDE.md` cuando no existe y conserva uno existente.
 

package/automatization/runners/claude/settings.json

@@ -1,4 +1,27 @@
 {
+  "permissions": {
+    "deny": [
+      "Read(.env)",
+      "Read(.env.local)",
+      "Read(.env.*.local)",
+      "Read(.npmrc)",
+      "Read(.netrc)",
+      "Read(_netrc)",
+      "Read(.pypirc)",
+      "Read(.dockercfg)",
+      "Read(id_rsa)",
+      "Read(id_dsa)",
+      "Read(id_ecdsa)",
+      "Read(id_ed25519)",
+      "Read(credentials)",
+      "Read(credentials*.json)",
+      "Read(*service-account*.json)",
+      "Read(*.pem)",
+      "Read(*.key)",
+      "Read(accesos.md)",
+      "Read(credenciales*)"
+    ]
+  },
   "hooks": {
     "PreToolUse": [
       {
@@ -12,6 +35,12 @@
         "hooks": [
           { "type": "command", "command": "$CLAUDE_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-files.sh" }
         ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-secrets-read.sh" }
+        ]
       }
     ],
     "Stop": [

package/automatization/runners/gemini/README.md

@@ -19,6 +19,7 @@ instalación vieja, `.gemini/commands/ops/` queda huérfano y se borra a mano.
 
 Gemini CLI tiene hooks nativos y el adaptador los usa: `BeforeTool` y `AfterAgent` en
 `.gemini/settings.json`, declarados en `manifest.json`. Sólo corren si la carpeta está marcada como
-confiable —`GEMINI.md` explica qué avisa Gemini cuando no lo está—.
+confiable —`GEMINI.md` explica qué avisa Gemini cuando no lo está—. `read_file` pasa por
+`guard-secrets-read.sh`, que frena leer una credencial; un `cat` por `run_shell_command` no lo ve.
 
 Comprueba la instalación con `node tools/ops.js automation doctor . gemini`.

package/automatization/runners/gemini/settings.json

@@ -27,6 +27,15 @@
             "command": "$GEMINI_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-files.sh"
           }
         ]
+      },
+      {
+        "matcher": "read_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$GEMINI_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-secrets-read.sh"
+          }
+        ]
       }
     ],
     "AfterAgent": [

package/engine/cli/args.js

@@ -32,6 +32,7 @@ const FLAGS = {
   adopt: [],
   agents: ['--json', '--own', '--system'],
   integration: ['--fixture'],
+  secrets: [],
   automation: ['--force'],
   learn: ['--flow', '--proposal', '--applied', '--archived', '--period'],
   evaluate: ['--cases', '--json', '--bench', '--force', '--record', '--flow'],

package/engine/cli/bootstrap.js

@@ -97,4 +97,4 @@ async function run(root, opciones, deps) {
   return { runner, provider, installed: true }
 }
 
-module.exports = { run, NO_RUNNER, NO_PROVIDER }
+module.exports = { run, validate, NO_RUNNER, NO_PROVIDER }

package/engine/cli/ops.js

@@ -95,11 +95,6 @@ async function init(target, cli) {
   if (existing.length && !force) {
     fail(`El destino no está vacío: ${root}. Usa --force para agregar solo archivos faltantes.`)
   }
-  IN.scaffold(root, { name, mode, force })
-  const relative = path.relative(process.cwd(), root)
-  const enter = relative && relative !== '.' ? `cd ${relative} && ` : ''
-  console.log(`\n✓ ${name}: sistema ops creado en ${root} (modo ${mode})`)
-
   // Preguntar exige una terminal, e instalar baja un paquete y escribe `node_modules`: las dos cosas
   // pasan cuando hay alguien mirando. Una corrida automatizada —CI, un contenedor, estas pruebas—
   // recibe la instancia materializada y decide por bandera, sin descargas ni preguntas implícitas.
@@ -112,6 +107,13 @@ async function init(target, cli) {
     interactive,
     install: cli.has('--install') || (interactive && !cli.has('--no-install')),
   }
+  // Se valida antes de escribir: un runner o una integración que no existen no pueden dejar una
+  // instancia hecha con el comando en error (caso 096). `BOOT.run` vuelve a validar con la misma función.
+  try { BOOT.validate(options) } catch (error) { fail(error.message, 2) }
+  IN.scaffold(root, { name, mode, force })
+  const relative = path.relative(process.cwd(), root)
+  const enter = relative && relative !== '.' ? `cd ${relative} && ` : ''
+  console.log(`\n✓ ${name}: sistema ops creado en ${root} (modo ${mode})`)
   let result
   try {
     result = await BOOT.run(root, options, {
@@ -166,6 +168,7 @@ function usage() {
   ops integration rebase <ops-root> <provider> <remote-key>
   ops integration reconcile <ops-root> <provider> <remote-key>
   ops integration writeback-plan <ops-root> <provider>
+  ops secrets check <ops-root>
   ops automation list <ops-root>
   ops automation list-hooks <ops-root>
   ops automation check <ops-root>
@@ -218,6 +221,7 @@ async function run(cli) {
   else if (command === 'integration') {
     await W.integration(arg[1], arg[2], arg[3], arg[4], cli)
   }
+  else if (command === 'secrets') W.secrets(arg[1], arg[2])
   else if (command === 'automation') W.automation(arg[1], arg[2], arg[3], cli)
   else if (command === 'learn') CAT.learn(arg[1], cli)
   else if (command === 'evaluate') CAT.evaluate(arg[1], arg[2], cli)

package/engine/cli/wiring.js

@@ -8,6 +8,7 @@ const fs = require('node:fs')
 const path = require('node:path')
 const F = require('../core/files')
 const I = require('../integrations/registry')
+const SE = require('../secrets')
 const A = require('../automation')
 const SC = require('../core/scan')
 const OB = require('../core/onboarding')
@@ -38,11 +39,18 @@ const INTEGRATION = {
     missing: 'Falta <provider>.',
     run: (root, provider) => {
       const source = path.join(IN.PROJECT_ROOT, 'template', 'integrations', provider)
-      if (!fs.existsSync(source)) fail(`Cauce no trae un adaptador para ${provider}.`, 2)
+      const fromCauce = fs.existsSync(source)
+      // Sin molde en Cauce no hay andamiaje que reponer: habilitar un proveedor propio es sólo el interruptor.
+      const own = !fromCauce && (providerRegistry(root).config.providers || {})[provider]
+        && fs.existsSync(path.join(root, 'integrations', provider))
+      if (!fromCauce && !own) {
+        fail(`Cauce no trae un adaptador para ${provider}. Uno propio vive en integrations/${provider}/ y se `
+          + `registra en integrations/config.json con "adapter": "./adapter.js"; con eso, enable lo conecta.`, 2)
+      }
       // Habilitar no es inicializar: repone lo que falte y conserva lo que ya esté. Una instancia que
       // trae el andamiaje de una versión anterior —o que ya tiene snapshots— sólo quiere el interruptor.
       providerRegistry(root)
-      IN.copyTemplate(source, path.join(root, 'integrations', provider), {}, true)
+      if (fromCauce) IN.copyTemplate(source, path.join(root, 'integrations', provider), {}, true)
       switchProvider(root, provider, true)
       console.log(`✓ ${provider}: conectado al proyecto y andamiaje en integrations/${provider}/.`)
       // Sólo se pide lo que falta: reencender un proveedor ya configurado no debería mandar a
@@ -277,8 +285,18 @@ function automation(action, rootArg, runnerName, cli) {
   fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, 2)
 }
 
+function secrets(action, rootArg) {
+  if (action !== 'check') fail(`Acción de secretos desconocida: ${action || '(vacía)'}`, 2)
+  const result = SE.check(opsRoot(rootArg))
+  if (!result.declared) return console.log(`Sin ${SE.DECLARATION}: no hay contrato de secretos que comprobar.`)
+  for (const warning of result.warnings) console.log(`⚠ ${warning}`)
+  for (const error of result.errors) console.error(`✗ ${error}`)
+  if (result.errors.length) fail(`${result.errors.length} error(es) en el contrato de secretos`)
+  console.log(`✓ contrato de secretos: ${result.current} servicio(s) al día`)
+}
+
 // `init` enciende un proveedor en la misma corrida en que crea la instancia, y ésta es la operación
 // que lo hace: se expone para que la composición no tenga que conocer la tabla entera.
 const enableProvider = (root, provider) => INTEGRATION.enable.run(root, provider)
 
-module.exports = { scan, onboard, integration, automation, enableProvider }
+module.exports = { scan, onboard, integration, automation, secrets, enableProvider }

package/engine/config/paths.js

@@ -10,7 +10,9 @@ const path = require('node:path')
 
 // `~` se expande sólo cuando es el prefijo entero. `~datos` es un nombre de directorio válido y no la
 // casa de nadie; expandirlo ahí convertiría una ruta relativa en una absoluta que el autor no escribió.
-function resolve(root, entry) {
+// La usa también el contrato de secretos para las rutas de sus identidades, por la misma razón que
+// arriba: una ruta declarada en un archivo del proyecto se resuelve igual la lea quien la lea.
+function resolvePath(root, entry) {
   return path.resolve(root, String(entry).replace(/^~(?=$|[/\\])/, os.homedir()))
 }
 
@@ -21,7 +23,7 @@ function resolve(root, entry) {
 function writableOutsideRoots(root, config) {
   const declared = config && Array.isArray(config.writableOutsideRoots) ? config.writableOutsideRoots : []
   return declared.filter((entry) => typeof entry === 'string' && entry.trim())
-    .map((entry) => ({ declared: entry, path: resolve(root, entry) }))
+    .map((entry) => ({ declared: entry, path: resolvePath(root, entry) }))
 }
 
-module.exports = { writableOutsideRoots }
+module.exports = { writableOutsideRoots, resolvePath }

package/engine/hooks/approval.js

@@ -41,10 +41,14 @@ function pending(root, files) {
   return files.filter((file) => !approved.has(file))
 }
 
-// Cómo se toma la salida angosta, dicho una vez porque ahora lo dicen cinco bloqueos. Nombra también la
-// variable: sigue existiendo, y esconderla haría que quien la necesite la descubra sin saber su alcance.
-const HOW = (variable) => `Aprobalo escribiendo esa(s) ruta(s) en planning/${APPROVAL}, una por línea: `
-  + `vale para ese conjunto y deja de valer en cuanto cambie. La variable ${variable}=1 sigue existiendo `
+// Cómo se toma la salida angosta, dicho una vez porque lo dicen todos los bloqueos que la tienen. Lleva
+// las líneas exactas porque cada guard coteja la ruta en la forma que tiene a mano —absoluta la que llega
+// de un Write, relativa al repositorio la que sale del índice— y una línea en la otra forma no pega: sin
+// decirla, lo que quedaba a mano era la variable (caso 089). Nombra también la variable: sigue
+// existiendo, y esconderla haría que quien la necesite la descubra sin saber su alcance.
+const HOW = (variable, lines) => `Aprobalo pegando tal cual en planning/${APPROVAL} estas líneas:\n`
+  + lines.map((line) => `  ${line}\n`).join('')
+  + `Valen para ese conjunto y dejan de valer en cuanto cambie. La variable ${variable}=1 sigue existiendo `
   + 'y apaga el guard para toda la sesión, que es por lo que no es la vía recomendada.'
 
 module.exports = { APPROVAL, read, pending, HOW }

package/engine/hooks/files.js

@@ -50,25 +50,50 @@ function alreadyShipped(file) {
 }
 
 
+// Qué archivo es una credencial, para los dos guards que la cuidan: `secrets`, que frena escribirla, y
+// `secrets-read`, que frena leerla. Devuelve el motivo, o vacío.
+function credential(input, raw) {
+  const base = path.basename(raw)
+  if (/^(?:\.env|\.env\..+)$/.test(base) && !/\.(?:example|sample|template|schema|dist|tpl)$/.test(base)) {
+    return 'parece contener secretos. Edita una plantilla o registra una acción humana.'
+  }
+  if (/^(?:accesos\.md|credenciales.*|credentials.*\.json|.*service-account.*\.json|.*\.(?:pem|key))$/i.test(base)) {
+    return 'parece un archivo de credenciales en texto plano.'
+  }
+  // Nombres de credencial que la herramienta escribe sola y que la lista anterior no cubría:
+  // `.npmrc` guarda el token de publicación, `.netrc` el de cualquier host, `id_rsa` y sus tres
+  // hermanas una clave privada de SSH, y `credentials` las de AWS. Los cuatro son estándar, no
+  // exóticos — y las claves SSH van por nombre de algoritmo, no por prefijo.
+  //
+  // Esto tapa un caso conocido; no vuelve completo al guard. La forma de decidir sigue siendo el
+  // nombre del archivo, así que otro formato pasa igual — ver «Qué son y qué no son» en el README.
+  if (/^(?:\.npmrc|\.netrc|_netrc|\.pypirc|\.dockercfg|id_(?:rsa|dsa|ecdsa|ed25519)|credentials)$/i.test(base)) {
+    return 'es un archivo de credenciales que su herramienta mantiene. No lo edites a mano.'
+  }
+  // Lo que ningún nombre delata: una identidad de máquina que el 088 declara puede llamarse
+  // `local-dev.env` (caso 092). Se lee sólo si la declaración existe, para no cargarla en cada hook.
+  const root = opsRoot(input)
+  if (!root || !fs.existsSync(path.join(root, 'organization', 'secrets.json'))) return ''
+  return require('../secrets').identityFiles(root).includes(path.resolve(cwdOf(input), raw))
+    ? 'es una identidad declarada en organization/secrets.json: la carga una persona.'
+    : ''
+}
+
 function secrets(input) {
   for (const file of filesOf(input)) {
-    const base = path.basename(file)
-    if (/^(?:\.env|\.env\..+)$/.test(base) && !/\.(?:example|sample|template|schema|dist|tpl)$/.test(base)) {
-      block(`${file} parece contener secretos. Edita una plantilla o registra una acción humana.`)
-    }
-    if (/^(?:accesos\.md|credenciales.*|credentials.*\.json|.*service-account.*\.json|.*\.(?:pem|key))$/i.test(base)) {
-      block(`${file} parece un archivo de credenciales en texto plano.`)
-    }
-    // Nombres de credencial que la herramienta escribe sola y que la lista anterior no cubría:
-    // `.npmrc` guarda el token de publicación, `.netrc` el de cualquier host, `id_rsa` y sus tres
-    // hermanas una clave privada de SSH, y `credentials` las de AWS. Los cuatro son estándar, no
-    // exóticos — y las claves SSH van por nombre de algoritmo, no por prefijo.
-    //
-    // Esto tapa un caso conocido; no vuelve completo al guard. La forma de decidir sigue siendo el
-    // nombre del archivo, así que otro formato pasa igual — ver «Qué son y qué no son» en el README.
-    if (/^(?:\.npmrc|\.netrc|_netrc|\.pypirc|\.dockercfg|id_(?:rsa|dsa|ecdsa|ed25519)|credentials)$/i.test(base)) {
-      block(`${file} es un archivo de credenciales que su herramienta mantiene. No lo edites a mano.`)
-    }
+    const reason = credential(input, file)
+    if (reason) block(`${file} ${reason}`)
+  }
+}
+
+// Leer una credencial la deja en el contexto de la sesión, y de ahí en los transcripts. Corre en su propio
+// grupo porque los guards de escritura frenarían leer fuera de las raíces o con el WIP vacío.
+function secretsRead(input) {
+  if (process.env.OPS_SECRETS_READ_OVERRIDE === '1') return
+  for (const file of filesOf(input)) {
+    if (!credential(input, file) || approved(input, file)) continue
+    block(`${file} es una credencial: leerla la deja en el contexto de la sesión. Si hace falta un valor, `
+      + `pedíselo a una persona.\n${AP.HOW('OPS_SECRETS_READ_OVERRIDE', [file])}`)
   }
 }
 
@@ -121,17 +146,18 @@ function testEvidence(input) {
     'decir que el comportamiento está y pasa a decir que nadie lo miró.\n' +
     'Si la aserción está mal, corregila; si el comportamiento cambió, cambialo junto con la prueba que ' +
     'lo fija. Si tiene que quedar afuera igual —flake conocido, entorno que acá no existe—, es una ' +
-    'decisión con dueño.\n' + AP.HOW('OPS_TEST_EVIDENCE_OVERRIDE')
+    'decisión con dueño.\n'
+  const how = (file) => AP.HOW('OPS_TEST_EVIDENCE_OVERRIDE', [file])
   for (const match of patchOf(input).matchAll(/^\*\*\* Delete File:\s*(.+)$/gm)) {
     const removed = match[1].trim()
-    if (isTestFile(removed) && !approved(input, removed)) block(`${removed} borra una prueba.\n${why}`)
+    if (isTestFile(removed) && !approved(input, removed)) block(`${removed} borra una prueba.\n${why}${how(removed)}`)
   }
   const content = contentOf(input)
   if (!content) return
   for (const raw of filesOf(input)) {
     if (!isTestFile(raw) || approved(input, raw)) continue
     for (const [marca, nombre] of TEST_OFF) {
-      if (marca.test(content)) block(`${raw} apaga una prueba con ${nombre}.\n${why}`)
+      if (marca.test(content)) block(`${raw} apaga una prueba con ${nombre}.\n${why}${how(raw)}`)
     }
   }
 }
@@ -150,6 +176,28 @@ function opsOwned(root, file) {
   return OPS_OWNED.some((prefix) => relative.startsWith(prefix))
 }
 
+// Producto es el código de una raíz declarada, y la instancia sidecar no lo es aunque viva dentro de una:
+// `init` escribe `..` como raíz en sidecar, así que la carpeta de la instancia cae adentro. En embedded la
+// raíz de ops **es** una raíz de producto, y ahí sólo se exime lo que la instancia posee. Lo que queda
+// fuera de toda raíz tampoco es producto: el límite de raíces ya lo juzgó, y si pasó es porque el proyecto
+// lo declaró en `writableOutsideRoots` (casos 089 y 090).
+//
+// `ops.config.json` se exime por nombre porque es la llave del límite de raíces: su mensaje manda a
+// editarlo, y frenar esa edición era el candado de arriba con otra forma.
+const INSTANCE_CONFIG = 'ops.config.json'
+
+function isProduct(root, file) {
+  if (opsOwned(root, file) || file === path.join(root, INSTANCE_CONFIG)) return false
+  const declared = configOf(root).workspaceRoots
+  const roots = (Array.isArray(declared) ? declared : [])
+    .filter((entry) => entry && typeof entry.path === 'string')
+    .map((entry) => path.resolve(root, entry.path))
+  // Sin raíces legibles no hay contra qué comparar, y se juzga como antes: frenar de más.
+  if (!roots.length) return true
+  if (outsideRoots(file, roots)) return false
+  return outsideRoots(file, [root]) || roots.includes(root)
+}
+
 // R1 y el paso 7 del protocolo piden el plan antes del primer cambio, y hasta acá nadie lo comprobaba:
 // tocar el archivo primero y redactar después la aceptación que lo justifica sale igual de verde que
 // hacerlo al revés, y se lee igual en DONE. Lo que se exige es lo mínimo que separa un plan de una
@@ -176,11 +224,10 @@ function planFirst(input) {
   const why = `${estado}, así que el plan todavía no está escrito.\n`
     + 'Escribí en tu planning/wip/<runner>.md la tarea y su plan aprobado —pasos numerados, cada uno con un estado '
     + 'verificable— y volvé al cambio. Si esto no es trabajo de una tarea, aprobá la ruta.\n'
-    + AP.HOW('OPS_PLAN_FIRST_OVERRIDE')
   for (const raw of filesOf(input)) {
-    if (opsOwned(root, path.resolve(cwdOf(input), raw))) continue
+    if (!isProduct(root, path.resolve(cwdOf(input), raw))) continue
     if (approved(input, raw)) continue
-    block(`${raw} cambia el producto sin plan. ${why}`)
+    block(`${raw} cambia el producto sin plan. ${why}${AP.HOW('OPS_PLAN_FIRST_OVERRIDE', [raw])}`)
   }
 }
 
@@ -254,7 +301,7 @@ function migrations(input) {
     if (!esMigracion.test(normalized)) continue
     if (approved(input, normalized)) continue
     if (destructiveSql.test(contentOf(input))) {
-      block(`${raw} contiene SQL destructivo.\n${AP.HOW('OPS_MIGRATIONS_OVERRIDE')}`)
+      block(`${raw} contiene SQL destructivo.\n${AP.HOW('OPS_MIGRATIONS_OVERRIDE', [normalized])}`)
     }
     // El mensaje nombra el hecho que sostiene el bloqueo y no su interpretación: «historial» era una
     // lectura que `existsSync` no podía dar, y se la daba igual sobre stubs de la misma sesión. Y lleva
@@ -264,7 +311,7 @@ function migrations(input) {
     const shipped = alreadyShipped(file)
     if (shipped) {
       block(`${raw} ${shipped}. Crea una nueva en vez de reescribirla.\n`
-        + AP.HOW('OPS_MIGRATIONS_OVERRIDE'))
+        + AP.HOW('OPS_MIGRATIONS_OVERRIDE', [normalized]))
     }
   }
 }
@@ -295,6 +342,6 @@ function engineWrites(input) {
 }
 
 module.exports = {
-  secrets, integrationSnapshot, generated, testEvidence, planFirst, workspaceBoundary,
+  secrets, secretsRead, integrationSnapshot, generated, testEvidence, planFirst, workspaceBoundary,
   migrations, engineWrites,
 }

package/engine/hooks/run.js

@@ -47,6 +47,7 @@ const guards = {
   'integration-snapshot': files.integrationSnapshot,
   'test-evidence': files.testEvidence,
   'plan-first': files.planFirst,
+  'secrets-read': files.secretsRead,
   'planning-drift': planningDrift,
 }
 
@@ -55,6 +56,7 @@ const hookGroups = {
   'pre-shell': ['destructive', 'git-add', 'dependencies', 'governance', 'verify', 'shell-boundary'],
   'pre-files': ['secrets', 'generated', 'workspace-boundary', 'engine', 'migrations',
     'integration-snapshot', 'test-evidence', 'plan-first'],
+  'pre-read': ['secrets-read'],
   stop: ['planning-drift'],
 }
 
@@ -94,6 +96,11 @@ const hookMetadata = [
     event: 'PreToolUse · files',
     purpose: 'Bloquea escribir secretos, claves privadas y credenciales en texto plano.',
   },
+  {
+    name: 'secrets-read',
+    event: 'PreToolUse · read',
+    purpose: 'Bloquea leer con la herramienta del runner una credencial conocida o declarada.',
+  },
   { name: 'generated', event: 'PreToolUse · files', purpose: 'Impide editar código generado manualmente.' },
   {
     name: 'workspace-boundary',

package/engine/hooks/shell.js

@@ -181,7 +181,7 @@ function dependencies(input) {
   // `package.json` dice «este manifiesto va sin su lock a propósito» y deja de valer en cuanto el
   // conjunto cambie. La rama de publicar no pasa por acá y no tiene ruta: sigue arriba, con su variable.
   const sinAprobar = (parent, names) => AP.pending(opsRoot(input),
-    names.map((name) => path.posix.join(parent === '.' ? '' : parent, name))).length
+    names.map((name) => path.posix.join(parent === '.' ? '' : parent, name)))
   // Un lock cuenta si está en disco **o** si el commit lo va a llevar, y la unión no es un detalle: el
   // disco solo perdía el que alguien borró del árbol sin stagear el borrado —sigue en el índice, sigue
   // en el próximo commit— y ahí la comprobación dejaba de dispararse justo cuando más hacía falta. Es
@@ -201,14 +201,15 @@ function dependencies(input) {
     if (onDisk.length > 1) {
       block(`${parent}: hay varios lockfiles (${onDisk.join(', ')}). Conserva uno solo.`)
     }
-    if (state.manifests.length && existingLocks.length && !state.locks.length
-      && sinAprobar(parent, state.manifests)) {
+    const manifests = sinAprobar(parent, state.manifests)
+    if (state.manifests.length && existingLocks.length && !state.locks.length && manifests.length) {
       block(`${parent}: cambió ${state.manifests.join(', ')} sin actualizar su lockfile.\n`
-        + AP.HOW('OPS_DEPENDENCIES_OVERRIDE'))
+        + AP.HOW('OPS_DEPENDENCIES_OVERRIDE', manifests))
     }
-    if (state.locks.length && !state.manifests.length && sinAprobar(parent, state.locks)) {
+    const lockfiles = sinAprobar(parent, state.locks)
+    if (state.locks.length && !state.manifests.length && lockfiles.length) {
       block(`${parent}: cambió ${state.locks.join(', ')} sin un cambio explícito en el manifest.\n`
-        + AP.HOW('OPS_DEPENDENCIES_OVERRIDE'))
+        + AP.HOW('OPS_DEPENDENCIES_OVERRIDE', lockfiles))
     }
   }
 }
@@ -348,8 +349,7 @@ function governance(input) {
   // entre una llave por operación y una puerta que quedó abierta.
   const pendientes = AP.pending(opsRoot(input), governed)
   if (!pendientes.length) return
-  const files = pendientes.map((file) => `  - ${file}`).join('\n')
-  block(`El commit toca gobernanza protegida:\n${files}\n${AP.HOW('OPS_GOVERNANCE_OVERRIDE')}`)
+  block(`El commit toca gobernanza protegida.\n${AP.HOW('OPS_GOVERNANCE_OVERRIDE', pendientes)}`)
 }
 
 function run(program, args, cwd, extra = {}) {
@@ -404,6 +404,7 @@ function commitTree(dir) {
     fs.rmSync(temp, { recursive: true, force: true })
     block(`no se pudo materializar el índice de ${dir} para correr los gates: ${written.output}`)
   }
+  const linked = []
   for (const line of lines) {
     if (!line.startsWith('!! ')) continue
     const name = line.slice(3).trim().replace(/\/$/, '')
@@ -424,6 +425,7 @@ function commitTree(dir) {
     if (fs.existsSync(link)) continue
     fs.mkdirSync(path.dirname(link), { recursive: true })
     fs.symlinkSync(path.join(dir, name), link, 'junction')
+    linked.push(name)
   }
   // Un índice materializado no trae `.git`, y un gate que llama a git —listar lo trackeado— falla ahí
   // por no encontrarlo: el guard frenaría un commit correcto por su propia mecánica. La copia se vuelve
@@ -441,7 +443,15 @@ function commitTree(dir) {
   // pierde en silencio. Se elige el silencio de acá sobre el de antes, que era escribir en la rama de
   // quien commitea; un proyecto con un gate así tiene que sacar esa escritura del gate.
   const started = run('git', ['init', '--quiet'], temp)
-  if (started.ok) run('git', ['add', '--all'], temp)
+  // Lo enlazado es entorno y no entra al índice de la copia, y el `.gitignore` no alcanza para eso: un
+  // patrón con barra final sólo cubre directorios, y un enlace no lo es para git. `add --all` lo agregaba
+  // y un gate que recorre lo trackeado lo leía como archivo del commit (caso 095).
+  if (started.ok) {
+    fs.mkdirSync(path.join(temp, '.git', 'info'), { recursive: true })
+    fs.appendFileSync(path.join(temp, '.git', 'info', 'exclude'),
+      linked.map((name) => `/${name.replace(/[\\*?[\]]/g, '\\$&')}\n`).join(''))
+    run('git', ['add', '--all'], temp)
+  }
   // Un gate no sólo lee su entorno: escribe en él. Lo ignorado se enlaza al original —eso es a propósito
   // y está arriba—, así que lo que el gate escriba cae en el árbol de quien commitea. Un gestor que se
   // sincroniza antes de correr un script lo lleva al extremo: ve que el árbol enlazado no coincide con
@@ -478,19 +488,20 @@ function verify(input) {
   // Acá lo aprobado es el conjunto staged entero: decir «autorizo commitear exactamente estas rutas»
   // es lo que un gate en rojo necesita, y cambia en cuanto se stagea una más. La lista sale del índice
   // y no de una regla, que es lo que la vuelve una operación y no un permiso.
-  const aprobado = !AP.pending(opsRoot(input), staged).length
+  const sinAprobar = AP.pending(opsRoot(input), staged)
+  const aprobado = !sinAprobar.length
   if (changedOpenApi && !hasApiGenerated && !aprobado) {
     block('Cambió una fuente OpenAPI/Swagger sin incluir código regenerado. Ejecuta el generador y '
-      + `stagea su salida.\n${AP.HOW('OPS_SKIP_VERIFY')}`)
+      + `stagea su salida.\n${AP.HOW('OPS_SKIP_VERIFY', sinAprobar)}`)
   }
   if (changedSqlSource && !hasSqlGenerated && !aprobado) {
     block('Cambió una consulta SQL fuente sin artefactos regenerados. Ejecuta el generador.\n'
-      + AP.HOW('OPS_SKIP_VERIFY'))
+      + AP.HOW('OPS_SKIP_VERIFY', sinAprobar))
   }
   if (!staged.some((file) => /\.(?:ts|tsx|js|jsx|mjs|cjs|go|py|html|css|scss|prisma)$/.test(file))) return
   const { root, temp, env } = commitTree(dir)
   try {
-    verifyGates(root, dir, aprobado, env, opsRoot(input))
+    verifyGates(root, dir, sinAprobar, env, opsRoot(input))
   } finally {
     if (temp) fs.rmSync(temp, { recursive: true, force: true })
   }
@@ -511,6 +522,11 @@ function verify(input) {
 // Se muestra **una** línea y acotada: la salida de un gate puede traer cualquier cosa del entorno, y lo
 // que hace falta para diagnosticar es la primera línea de error, no el volcado.
 const ERROR_LINE = /error|err[_!]|fail|abort|not found|cannot|no such/i
+// Cómo marca un reporte de pruebas cada resultado: `node --test` en spec y en TAP, y `go test`. Van sólo
+// las comprobadas contra la herramienta (caso 094): el nombre de una prueba verde puede decir «error», y
+// sin mirar la marca la búsqueda por palabra se quedaba con ella y el mensaje escondía la roja.
+const FAILED_TEST = /^(?:✖|not ok\b|--- FAIL:)/
+const PASSED_TEST = /^(?:✔|ok\b|--- PASS:)/
 const MAX_LINE = 160
 function fallo(gate, result) {
   // La línea que empieza con `>` es el eco del script que npm y pnpm imprimen antes de correrlo, así
@@ -519,7 +535,8 @@ function fallo(gate, result) {
   // palabra de error gana siempre.
   const lines = (result.output || '').split('\n').map((one) => one.trim())
     .filter((one) => one && !one.startsWith('>'))
-  const line = lines.find((one) => ERROR_LINE.test(one)) || lines[0] || ''
+  const line = lines.find((one) => FAILED_TEST.test(one))
+    || lines.find((one) => !PASSED_TEST.test(one) && ERROR_LINE.test(one)) || lines[0] || ''
   return { gate, status: result.status, ms: result.ms, line: line.slice(0, MAX_LINE) }
 }
 
@@ -538,7 +555,7 @@ function comoSeLee(failures) {
     + 'una suite, así que mirá si llegaron a ejecutarse antes de aprobar esto como un rojo conocido.'
 }
 
-function verifyGates(root, dir, aprobado, env, ops) {
+function verifyGates(root, dir, sinAprobar, env, ops) {
   const failures = []
   if (fs.existsSync(path.join(root, 'package.json'))) {
     const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
@@ -572,13 +589,13 @@ function verifyGates(root, dir, aprobado, env, ops) {
       if (!result.ok) failures.push(fallo('make test', result))
     }
   }
-  if (!failures.length || aprobado) return
+  if (!failures.length || !sinAprobar.length) return
   // Se dice sobre qué corrió cuando no fue el árbol: un fallo que no se reproduce escribiendo el mismo
   // comando a mano se lee como que el guard miente, y lo que pasó es que midió lo que se va a grabar.
   const donde = root === dir ? '' : '\nCorrió sobre el índice, que es lo que el commit graba: si en tu '
     + 'directorio pasa, es que en disco tenés algo que no está staged.'
   block(`Verify falló en ${path.basename(dir)}: ${comoSeLee(failures)}\nNo se commitea en rojo.${donde}\n`
-    + AP.HOW('OPS_SKIP_VERIFY'))
+    + AP.HOW('OPS_SKIP_VERIFY', sinAprobar))
 }
 
 module.exports = { destructive, gitAdd, dependencies, governance, verify, shellBoundary, run }

package/engine/integrations/providers/jira.js

@@ -161,4 +161,4 @@ async function fetchItems(config, options = {}) {
   return issues.map((issue) => normalizeIssue(issue, config))
 }
 
-module.exports = { fetchItems, normalizeFixture, validateConfig }
+module.exports = { contract: 1, fetchItems, normalizeFixture, validateConfig }

package/engine/integrations/registry.js

@@ -37,9 +37,31 @@ function providerConfig(root, name) {
   return { registry, entry, config: readJson(configFile), configFile }
 }
 
-function adapter(name) {
-  if (name === 'jira') return require('./providers/jira')
-  throw new Error(`No existe adaptador para ${name}`)
+// Los adaptadores que trae Cauce. Uno de la empresa no va acá: se declara con una ruta en el registro de
+// la instancia y vive en la carpeta de su proveedor (caso 091).
+const BUILTIN = { jira: () => require('./providers/jira') }
+// La versión del contrato que el motor sabe llamar. A un adaptador de la empresa no lo toca `upgrade`, así
+// que sin esto un cambio de interfaz lo rompería en silencio.
+const CONTRACT = 1
+const CONTRACT_FUNCTIONS = ['validateConfig', 'fetchItems', 'normalizeFixture']
+
+function adapter(root, name, entry = {}) {
+  const declared = String(entry.adapter || '')
+  let impl
+  if (Object.hasOwn(BUILTIN, declared)) impl = BUILTIN[declared]()
+  else if (declared.startsWith('./')) {
+    const base = path.join(root, 'integrations', name)
+    impl = require(F.assertWithin(base, path.resolve(base, declared), `${name}: adapter`))
+  } else {
+    throw new Error(`No existe adaptador para ${declared || name}: usá uno de Cauce `
+      + `(${Object.keys(BUILTIN).join(', ')}) o una ruta ./ dentro de integrations/${name}/`)
+  }
+  if (impl.contract !== CONTRACT) {
+    throw new Error(`el motor sabe llamar contract ${CONTRACT} y el adaptador declara ${impl.contract}`)
+  }
+  const missing = CONTRACT_FUNCTIONS.filter((fn) => typeof impl[fn] !== 'function')
+  if (missing.length) throw new Error(`al adaptador le falta ${missing.join(', ')}`)
+  return impl
 }
 
 function sensitivePath(value, trail = '') {
@@ -91,7 +113,7 @@ function validate(root, onlyProvider = '') {
     const secret = sensitivePath(loaded.config)
     if (secret) errors.push(`${name}: ${secret} no puede contener secretos; usa una variable de entorno`)
     try {
-      adapter(name).validateConfig(loaded.config, errors)
+      adapter(root, name, loaded.entry).validateConfig(loaded.config, errors)
     } catch (error) {
       errors.push(`${name}: ${error.message}`)
     }
@@ -185,7 +207,7 @@ async function sync(root, name, options = {}) {
   // Son dos interruptores y se exigen los dos: el del registro dice que el proveedor está conectado
   // al proyecto, y el suyo que hay a dónde apuntar.
   if (!entry.enabled || !config.enabled) throw new Error(`${name} está deshabilitado`)
-  const provider = adapter(name)
+  const provider = adapter(root, name, entry)
   const items = options.fixture
     ? provider.normalizeFixture(readJson(path.resolve(options.fixture)), config)
     : await provider.fetchItems(config)
@@ -420,6 +442,7 @@ module.exports = {
   providerConfig,
   reconcile,
   safeSegment,
+  sensitivePath,
   sync,
   validate,
   writebackPlan,

package/engine/secrets/index.js

@@ -0,0 +1,201 @@
+'use strict'
+
+// El contrato de secretos que una empresa comparte entre sus repositorios, y el chequeo sin red que lo
+// hace cumplir (caso 088). La base no conoce ningún gestor: lee `organization/secrets.json`, comprueba
+// que sus referencias cierren, que ninguna credencial viva dentro de un repositorio y que cada copia de
+// un archivo compartido coincida con la canónica que guarda la instancia. Lo que habla con el gestor y
+// lo que se copia es de la empresa; esto sólo dice qué quedó atrás y cómo ponerlo al día.
+//
+// Compara los servicios de **una** instancia. Una empresa con varios proyectos los declara como raíces
+// de la misma, y eso es lo que hace que un esqueleto y sus derivados se midan contra la misma copia.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const crypto = require('node:crypto')
+const { spawnSync } = require('node:child_process')
+const F = require('../core/files')
+const { resolvePath } = require('../config/paths')
+const { sensitivePath } = require('../integrations/registry')
+
+const DECLARATION = path.join('organization', 'secrets.json')
+const TOP_LEVEL = ['schemaVersion', 'accounts', 'projects', 'identities', 'shared', 'services']
+const SOURCES = ['file', 'ci-secret']
+
+function inside(base, target) {
+  try { F.assertWithin(base, target); return true } catch { return false }
+}
+
+const digest = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+
+// Una credencial dentro de un repositorio es la que se commitea por error, y el repositorio puede ser
+// uno que la instancia no declara: sólo git sabe si el directorio está en un árbol de trabajo. Sin
+// `GIT_DIR` heredado, que respondería por otro repositorio (caso 045).
+function inRepository(file) {
+  const dir = path.dirname(file)
+  if (!fs.existsSync(dir)) return false
+  const env = { ...process.env }
+  delete env.GIT_DIR
+  delete env.GIT_WORK_TREE
+  const result = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8', env })
+  return result.status === 0 && result.stdout.trim() === 'true'
+}
+
+function readJson(file) {
+  try { return { value: JSON.parse(fs.readFileSync(file, 'utf8')) } } catch (error) { return { error } }
+}
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+// Una sección que falta es una sección vacía; una que no es objeto es un error y se lee como vacía para
+// que el resto del chequeo siga diciendo lo que encuentre.
+function section(declaration, name, errors) {
+  const value = declaration[name]
+  if (value === undefined) return {}
+  if (isObject(value) && Object.values(value).every(isObject)) return value
+  errors.push(`${DECLARATION}: ${name} debe ser un objeto de entradas`)
+  return {}
+}
+
+function reference(errors, where, field, value, declared, sectionName) {
+  if (value === undefined) return errors.push(`${where}: falta ${field}`)
+  if (!Object.hasOwn(declared, value)) {
+    errors.push(`${where}: ${field} «${value}» no está declarado en ${sectionName}`)
+  }
+}
+
+function checkIdentities(context) {
+  const { root, identities, accounts, workspaces, errors, warnings } = context
+  for (const [name, identity] of Object.entries(identities)) {
+    const where = `identities.${name}`
+    reference(errors, where, 'account', identity.account, accounts, 'accounts')
+    if (!SOURCES.includes(identity.source)) {
+      errors.push(`${where}: source debe ser ${SOURCES.join(' o ')}`)
+      continue
+    }
+    if (identity.source === 'ci-secret') {
+      if (identity.file !== undefined) errors.push(`${where}: una identidad ci-secret vive en el CI y no lleva file`)
+      continue
+    }
+    if (typeof identity.file !== 'string' || !identity.file.trim()) {
+      errors.push(`${where}: una identidad file necesita la ruta de su archivo`)
+      continue
+    }
+    const file = resolvePath(root, identity.file)
+    const base = [root, ...workspaces.map((workspace) => workspace.dir)].find((dir) => inside(dir, file))
+    if (base) errors.push(`${where}: ${file} está dentro de ${base}; una credencial vive fuera de todo repositorio`)
+    else if (inRepository(file)) {
+      errors.push(`${where}: ${file} está dentro de un repositorio de git; una credencial vive fuera de todos`)
+    }
+    if (!fs.existsSync(file)) {
+      warnings.push(`${where}: ${file} no está en esta máquina; la carga una persona, el chequeo no la lee`)
+    }
+  }
+}
+
+// Las copias de cada servicio contra la canónica. Devuelve cuántos servicios quedaron al día.
+function checkServices(context) {
+  const { root, declaration, services, projects, identities, shared, workspaces, errors } = context
+  let current = 0
+  for (const [name, service] of Object.entries(services)) {
+    const where = `services.${name}`
+    const before = errors.length
+    reference(errors, where, 'project', service.project, projects, 'projects')
+    if (service.identity !== undefined) {
+      reference(errors, where, 'identity', service.identity, identities, 'identities')
+    }
+    const workspace = workspaces.find((entry) => entry.name === service.root)
+    if (!workspace) {
+      errors.push(`${where}: root «${service.root}» no es una raíz de ops.config.json`)
+      continue
+    }
+    if (!fs.existsSync(workspace.dir)) {
+      errors.push(`${where}: no existe ${workspace.dir}`)
+      continue
+    }
+    const schema = service.schema || '.env.schema'
+    if (!fs.existsSync(path.resolve(workspace.dir, schema))) {
+      errors.push(`${where}: falta ${schema} en ${workspace.dir}`)
+    }
+    for (const [target, key] of Object.entries(isObject(service.files) ? service.files : {})) {
+      if (!Object.hasOwn(shared, key)) {
+        errors.push(`${where}: files.${target} apunta a «${key}», que no está declarado en shared`)
+        continue
+      }
+      const copy = path.resolve(workspace.dir, target)
+      const canonical = path.resolve(root, declaration.shared[key])
+      if (!inside(workspace.dir, copy)) errors.push(`${where}: ${target} está fuera de su raíz`)
+      else if (!fs.existsSync(canonical)) continue
+      else if (!fs.existsSync(copy)) errors.push(`${where}: falta ${target}; copiala de ${declaration.shared[key]}`)
+      else if (digest(copy) !== digest(canonical)) {
+        errors.push(`${where}: ${target} no coincide con ${declaration.shared[key]}; para ponerla al día: `
+          + `cp ${canonical} ${copy}`)
+      }
+    }
+    if (errors.length === before) current += 1
+  }
+  return current
+}
+
+function checkShared(root, shared, errors) {
+  for (const [key, value] of Object.entries(shared)) {
+    const file = path.resolve(root, String(value))
+    if (!inside(root, file)) errors.push(`shared.${key}: ${value} está fuera de la instancia`)
+    else if (!fs.existsSync(file)) errors.push(`shared.${key}: no existe ${value}`)
+  }
+}
+
+// El chequeo entero. Sin declaración no hay nada que comprobar, y no es un error: la mayoría de las
+// instancias no la usa.
+function check(root) {
+  const file = path.join(root, DECLARATION)
+  if (!fs.existsSync(file)) return { declared: false, errors: [], warnings: [], current: 0 }
+  const errors = []
+  const warnings = []
+  const done = () => ({ declared: true, errors, warnings, current })
+  let current = 0
+  const read = readJson(file)
+  if (read.error) errors.push(`${DECLARATION}: JSON inválido (${read.error.message})`)
+  else if (!isObject(read.value)) errors.push(`${DECLARATION}: debe ser un objeto`)
+  if (errors.length) return done()
+  const declaration = read.value
+  for (const key of Object.keys(declaration)) {
+    if (!TOP_LEVEL.includes(key)) errors.push(`${DECLARATION}: propiedad desconocida ${key}`)
+  }
+  if (declaration.schemaVersion !== 1) errors.push(`${DECLARATION}: schemaVersion debe ser 1`)
+  const secret = sensitivePath(declaration)
+  if (secret) errors.push(`${DECLARATION}: ${secret} tiene forma de secreto; acá van referencias, nunca valores`)
+  const config = readJson(path.join(root, 'ops.config.json'))
+  const roots = config.error || !Array.isArray(config.value.workspaceRoots) ? [] : config.value.workspaceRoots
+  if (config.error) errors.push(`ops.config.json: no se puede leer (${config.error.message})`)
+  const workspaces = roots.filter(isObject).map((entry) => ({ name: entry.name, dir: path.resolve(root, entry.path) }))
+  const accounts = section(declaration, 'accounts', errors)
+  const projects = section(declaration, 'projects', errors)
+  const identities = section(declaration, 'identities', errors)
+  const services = section(declaration, 'services', errors)
+  const shared = isObject(declaration.shared) ? declaration.shared : {}
+  if (declaration.shared !== undefined && !isObject(declaration.shared)) {
+    errors.push(`${DECLARATION}: shared debe ser un objeto de rutas`)
+  }
+  for (const [name, project] of Object.entries(projects)) {
+    reference(errors, `projects.${name}`, 'account', project.account, accounts, 'accounts')
+  }
+  const context = { root, declaration, accounts, projects, identities, services, shared, workspaces, errors, warnings }
+  checkIdentities(context)
+  checkShared(root, shared, errors)
+  current = checkServices(context)
+  return done()
+}
+
+// Las rutas de las identidades que la declaración pone en disco, resueltas como las resuelve el chequeo.
+// Las lee el guard de secretos (caso 092); una declaración ausente o ilegible no aporta ninguna, porque
+// decir qué está mal es trabajo del chequeo.
+function identityFiles(root) {
+  const read = readJson(path.join(root, DECLARATION))
+  if (read.error || !isObject(read.value) || !isObject(read.value.identities)) return []
+  return Object.values(read.value.identities)
+    .filter((identity) => isObject(identity) && identity.source === 'file')
+    .filter((identity) => typeof identity.file === 'string' && identity.file.trim())
+    .map((identity) => resolvePath(root, identity.file))
+}
+
+module.exports = { DECLARATION, check, identityFiles }

package/package.json

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

package/template/AGENTS.md

@@ -151,6 +151,7 @@ y eso lo deja apagado **hasta que cierres la sesión**, no para un comando.
 | `OPS_TEST_EVIDENCE_OVERRIDE=1` | el de evidencia de pruebas |
 | `OPS_DEPENDENCIES_OVERRIDE=1` | el de dependencias, incluido publicar e instalar global |
 | `OPS_PLAN_FIRST_OVERRIDE=1` | el que exige plan antes de cambiar el producto |
+| `OPS_SECRETS_READ_OVERRIDE=1` | el que frena leer una credencial con la herramienta del runner |
 | `OPS_SKIP_VERIFY=1` | el que corre los gates |
 
 Por eso la aprobación es la vía recomendada y esto es lo que queda cuando no alcanza: prendela para lo

package/template/integrations/README.md

@@ -22,3 +22,24 @@ node tools/ops.js integration promote . jira KEY-123
 El motor compara base reconciliada, remoto actual y curación local. Usa `reset` para adoptar el remoto,
 `reconcile` para conservar la edición local sobre la nueva base y `rebase` para reparar hashes mecánicos.
 Ninguno de esos comandos escribe en el proveedor.
+
+## Un proveedor propio
+
+Cauce trae Jira. Para conectar otra herramienta, el adaptador se escribe acá, en la instancia, sin tocar
+Cauce:
+
+1. Crear `integrations/<nombre>/` con su `config.json` y el adaptador, por ejemplo `adapter.js`.
+2. Registrarlo en `config.json` con la ruta, relativa a `integrations/<nombre>/`:
+   `"adapter": "./adapter.js"`. Un nombre sin `./` —`"jira"`— es un adaptador de Cauce.
+3. `node tools/ops.js integration enable . <nombre>` lo conecta y `integration check .` lo valida.
+
+El adaptador exporta `contract: 1` y tres funciones:
+
+- `validateConfig(config, errors)` valida sin conectarse, y empuja a `errors` lo que impide correr.
+- `fetchItems(config, options)` hace la lectura paginada completa del proveedor.
+- `normalizeFixture(payload, config)` usa el mismo normalizador sin red, para pruebas e importaciones.
+
+`check` rechaza un adaptador con otra versión o sin alguna de las funciones, y una ruta que salga de
+`integrations/<nombre>/`. Puede ser CommonJS o ESM. El motor lo ejecuta con los mismos permisos que el
+CLI: la contención es de ruta, no de capacidad. Staging, revisión, promoción y validación son los mismos
+que para Jira; el adaptador sólo traduce la API del proveedor.

package/template/organization/README.md

@@ -18,4 +18,56 @@ Recomendados, sin molde: escribilos con la forma que le sirva a este proyecto.
 La lista no es cerrada. Todo hecho de negocio o producto que cambie lentamente vive acá —una guía de
 marca, un manual de operación, un pipeline de contenido— aunque no tenga una línea propia arriba.
 
+Opcional, con forma fija: `secrets.json`, el contrato de secretos que la empresa comparte entre sus
+repositorios. Ver «Secretos compartidos» abajo.
+
 Principio: cada hecho tiene un dueño. Enlaza en vez de copiar información que ya vive en otro lugar.
+
+## Secretos compartidos
+
+Cuando varios servicios usan el mismo gestor de secretos —Infisical, Vault, Doppler—, terminan con los
+mismos scripts y workflows copiados en cada repositorio, y la copia que se quedó atrás no avisa.
+`secrets.json` declara ese contrato una vez y `node tools/ops.js secrets check .` lo compara contra cada
+servicio **sin conectarse a nada**. Cauce no conoce ningún gestor: lo que habla con él es de la empresa.
+
+```json
+{
+  "schemaVersion": 1,
+  "accounts":   { "principal": { "url": "https://app.infisical.com" } },
+  "projects":   { "tienda": { "account": "principal" } },
+  "identities": {
+    "local-dev": { "account": "principal", "source": "file", "file": "~/.config/acme/local-dev.env" },
+    "ci":        { "account": "principal", "source": "ci-secret" }
+  },
+  "shared":   { "check-schema": "organization/secrets/check-schema.py" },
+  "services": {
+    "api": { "root": "api", "project": "tienda", "identity": "local-dev",
+             "files": { "scripts/check-schema.py": "check-schema" } }
+  }
+}
+```
+
+- **Nunca guarda un valor.** Una clave con forma de secreto —`token`, `password`, `secret`— es un error.
+  Las entradas pueden llevar otros campos que lean los scripts de la empresa (un id de proyecto, sus
+  ambientes); el chequeo no los mira.
+- **Una identidad por nivel de acceso, no por repositorio.** Compartir credenciales es apuntar al mismo
+  alias, y rotar es cambiar un archivo. `source: file` es un archivo **fuera de todo repositorio**, que
+  carga una persona; `source: ci-secret` vive en el CI y no lleva ruta.
+- **`shared` guarda la copia canónica** de cada archivo compartido, dentro de esta instancia, y
+  `services.<nombre>.files` dice dónde va en el servicio. Cada `root` es una raíz de `ops.config.json`.
+- **Varios proyectos, una instancia.** El chequeo compara los servicios de esta instancia; para que el
+  esqueleto de un proyecto y los servicios de otro se midan contra lo mismo, los dos van como raíces acá.
+
+`secrets check` falla si una copia no coincide con la canónica —y dice el `cp` que la pone al día—, si
+falta, si una referencia no cierra o si una credencial está dentro de un repositorio. Una identidad que
+no está en esta máquina es una advertencia: en el CI no tiene por qué estar.
+
+El recorrido:
+
+- **Adoptar un servicio**: declararlo, copiar los archivos de `shared` y correr `secrets check`. Cargar
+  la identidad en su archivo y los secretos del CI lo hace una persona: el guard de secretos frena que
+  un agente escriba un `.env.*`, y es lo correcto.
+- **Mantener**: se cambia la copia canónica, `secrets check` lista los servicios que quedaron atrás y
+  cada uno se actualiza con un commit en su repositorio.
+- **Rotar**: se reemplaza el archivo de la identidad; los servicios que la usan no cambian.
+- **Dar de baja**: se saca el servicio de `services` y se borran sus copias en su repositorio.

package/template/planning/adr/README.md

@@ -47,3 +47,4 @@ archivo lo mantiene Cauce, así que una fila agregada acá se perdería en el pr
 - [OPS-004](system/OPS-004-promocion-humana-y-evidencia-verificable.md): promoción controlada y verificable.
 - [OPS-005](system/OPS-005-catalogo-en-el-paquete.md): el catálogo viaja dentro del paquete.
 - [OPS-006](system/OPS-006-ceremonia-por-superficie.md): la ceremonia escala con la superficie del cambio.
+- [OPS-007](system/OPS-007-contrato-de-secretos-compartido.md): un contrato de secretos compartido, sin gestor.

package/template/planning/adr/system/OPS-007-contrato-de-secretos-compartido.md

@@ -0,0 +1,62 @@
+# OPS-007 — Un contrato de secretos compartido, sin conocer ningún gestor
+
+**Estado:** Aceptado
+**Fecha:** 2026-09-10
+
+> Decide qué parte del manejo de secretos es de la base; el gestor, sus scripts y su CI siguen siendo de
+> la empresa.
+
+## Contexto
+
+Una empresa que adopta un gestor de secretos termina con el mismo modelo copiado en cada repositorio:
+la identidad con que se lee el gestor, un script que compara el gestor contra el contrato de variables y
+los workflows que avisan en el PR. Nada dice qué servicio usa qué cuenta ni qué identidad, y nada detecta
+que una copia se quedó atrás. En una instancia real se contaron dieciséis copias de un mismo script en
+tres variantes, y el arreglo que tenía una sola no había llegado ni al esqueleto del que salen los
+servicios nuevos.
+
+`integrations/` no sirve para esto: su ciclo es de contenido de trabajo que baja a planning (OPS-003), y
+su README prohíbe guardar secretos ahí.
+
+## Decisión
+
+**La base declara y compara; no se conecta, no genera y no conoce ningún gestor.**
+
+- La declaración vive en `organization/secrets.json`, que es del proyecto: cuentas, proyectos,
+  identidades, servicios y los archivos que comparten. Nunca un valor: una clave con forma de secreto es
+  un error.
+- Una identidad es un nivel de acceso, no un repositorio. `source: file` es un archivo **fuera de todo
+  repositorio**, que carga una persona; `source: ci-secret` vive en el CI.
+- La copia canónica de cada archivo compartido vive en la instancia. `ops secrets check` compara cada
+  copia de cada servicio contra ella por hash, sin red, y dice el `cp` que la pone al día. Cauce no
+  escribe en los repositorios de producto.
+- El chequeo compara los servicios de una instancia. Una empresa con varios proyectos los declara como
+  raíces de la misma instancia, que es lo que hace que un esqueleto y sus derivados se midan contra lo
+  mismo.
+
+## Alternativas consideradas
+
+- **Un adaptador de la empresa que genere los archivos**: flexible, pero obliga al motor a cargar código
+  de la instancia y a versionar una interfaz, para resolver lo mismo que una copia comparada por hash.
+- **El adaptador como paquete versionado que cada instancia instala**: mantiene una instancia por
+  proyecto a cambio de publicar y versionar un paquete más.
+- **Un workflow reutilizable compartido**: una sola copia, pero supone GitHub y una organización, y deja
+  a la base atada a un proveedor de CI.
+- **Hacerlo un proveedor de `integrations/`**: su staging, reconciliación y promoción no se aplican a
+  secretos.
+
+## Consecuencias
+
+**Ganamos:** la copia que se quedó atrás se ve, con su arreglo al lado; rotar una identidad compartida
+es cambiar un archivo; y la base sigue sin saber de ningún gestor.
+
+**Costos que aceptamos:** un arreglo sigue siendo un commit por repositorio —el chequeo los lista, no los
+aplica—. Juntar varios proyectos en una instancia comparte también su `planning/`. Y una credencial
+dentro de un repositorio es un error aunque esté ignorada por git: es la copia por repositorio que esta
+decisión viene a sacar.
+
+## Estado de implementación
+
+Implementado en 0.80.0: `organization/secrets.json`, `ops secrets check` y el recorrido documentado en
+`organization/README.md`. Cauce no trae adaptadores ni un workflow de ejemplo que corra el chequeo en CI;
+correrlo ahí es un paso de la empresa.