@ingeniomaps/cauce 0.79.0 → 0.81.0

package/engine/hooks/shell.js

@@ -10,9 +10,10 @@ const path = require('node:path')
 const { spawnSync } = require('node:child_process')
 const {
   commandOf, cwdOf, block, isCommit, stagedForCommit, pushAllowed,
-  writableRoots, outsideRoots, DECLARE_IT, unquoted, findOpsRoot, withoutGitGlobals,
+  writableRoots, outsideRoots, DECLARE_IT, unquoted, opsRoot, withoutGitGlobals,
 } = require('./input')
 const AP = require('./approval')
+const { selfApproval } = require('./self-approval')
 const EV = require('../core/evidence')
 
 // Dónde empieza y dónde termina una palabra dentro de un comando. Tres reglas de la tabla de abajo lo
@@ -48,12 +49,6 @@ const MISMO = String.raw`[^;&|\n]`
 // `bash -c "git push origin main"` y `eval "git reset --hard"` siguen cayendo, comprobado. Queda afuera
 // la sustitución dentro del propio mensaje —`git commit -m "$(...)"` corre y ya no se ve—, que es
 // evasión y no la forma habitual.
-// La raíz donde vive `planning/`, que es donde se busca la aprobación. Los cuatro guards que la
-// consultan la resuelven igual, así que se resuelve una vez.
-function opsRoot(input) {
-  return findOpsRoot(process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || cwdOf(input))
-}
-
 function destructive(input) {
   const raw = commandOf(input)
   // Las opciones globales de `git` se sacan acá y no en cada regla: toda regla de abajo que mire un
@@ -181,7 +176,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)), input)
   // 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 +196,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, input))
     }
-    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, input))
     }
   }
 }
@@ -305,17 +301,21 @@ function writesWithBase(command, cwd) {
 
 function shellBoundary(input) {
   const allowed = writableRoots(input)
-  if (!allowed) return
   for (const { raw, base } of writesWithBase(commandOf(input), cwdOf(input))) {
     // Una ruta absoluta no depende del `cd`, así que un destino que no se sabe no la vuelve injuzgable.
     // Al revés sí: sin saber desde dónde se resuelve, una relativa no se puede verificar, y un guard que
     // no puede verificar no autoriza —el criterio que fijó el 031 para el índice—.
     if (!path.isAbsolute(raw) && base === null) {
+      if (!allowed) continue
       block(`el comando hace \`cd\` a un destino que no se puede resolver acá, así que no hay contra qué `
         + `resolver ${raw}. Escribí la ruta absoluta, o hacé el \`cd\` en un comando aparte.`)
     }
-    const file = path.resolve(base, raw)
-    if (NEUTRAL.some((pattern) => pattern.test(file))) continue
+    const file = path.resolve(base || '/', raw)
+    // El canal por el que la persona aprueba no es un destino más: se juzga aunque no haya raíces
+    // declaradas y aunque caiga en el temporal, que el resto de este guard deja pasar (caso 098).
+    const own = selfApproval(input, file)
+    if (own) block(own)
+    if (!allowed || NEUTRAL.some((pattern) => pattern.test(file))) continue
     if (outsideRoots(file, allowed)) {
       block(`el comando escribe en ${file}, fuera de las raíces declaradas en ops.config.json. ${DECLARE_IT}`)
     }
@@ -346,10 +346,9 @@ function governance(input) {
   // 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 pendientes = AP.pending(opsRoot(input), governed)
+  const pendientes = AP.pending(opsRoot(input), governed, input)
   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, input)}`)
 }
 
 function run(program, args, cwd, extra = {}) {
@@ -404,6 +403,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 +424,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 +442,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 +487,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, input)
+  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, input)}`)
   }
   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, input))
   }
   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, input)
   } finally {
     if (temp) fs.rmSync(temp, { recursive: true, force: true })
   }
@@ -511,6 +521,15 @@ 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. 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. Comprobadas con la salida entubada, como la ve un gate:
+// `node --test` en spec y en TAP (Node 24.18.0), `go test` (go 1.26.3), jest 30.5.1 (`● nombre`, y
+// `● Test suite failed to run`), vitest 5.0.0 (`× nombre`), mocha 12.0.1 (`1) nombre`; la verde es `✔`) y
+// pytest 9.1.1 (`FAILED archivo::prueba` en el resumen; `::prueba PASSED` la verde con `-v`). Jest y vitest
+// no imprimen las verdes sin `--verbose`, así que de ellos no hay marca de éxito.
+const FAILED_TEST = /^(?:✖|not ok\b|--- FAIL:|● |× |\d+\) |FAILED )/
+const PASSED_TEST = /^(?:✔|ok\b|--- PASS:)|::\S+ PASSED\b/
 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 +538,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 +558,8 @@ 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, input) {
+  const ops = opsRoot(input)
   const failures = []
   if (fs.existsSync(path.join(root, 'package.json'))) {
     const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
@@ -572,13 +593,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, input))
 }
 
 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.81.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "keywords": [
     "planning",

package/template/AGENTS.md

@@ -103,9 +103,19 @@ Un guard existente **no se edita**: `upgrade` detecta el cambio y se detiene ant
 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.
 
-**La salida de todos ellos es la misma**: escribir en `planning/.ops-approval` las rutas que autorizás,
-una por línea, con `#` para lo que no sea una ruta. Es un solo archivo para todos los guards, porque lo
-que escribís son rutas y quién las mira lo decide qué guard esté juzgando esa ruta.
+**Si lo pediste vos en el chat, no hace falta nada.** Los guards contienen al agente cuando decide solo o
+cuando trabaja dentro de un recorrido; lo que vos pedís directo no se frena. Nombrá lo que querés que
+toque —«borrá la prueba de altas», «reescribí la migración 004»— y pasa sin preguntarte de nuevo. Si tu
+pedido no lo nombraba y algo se frena, el agente te dice qué y por qué: contestá «dale» y pasa exactamente
+eso. Y `plan-first` no te pide un plan cuando el cambio lo pediste vos: el plan es para el trabajo que va
+por tareas. Funciona en Claude Code, Codex y Gemini, que le avisan a Cauce cuando mandás un mensaje; en
+Antigravity, y cuando nadie está en el chat —CI, un recorrido, un subagente—, queda el archivo de abajo.
+
+**Sin chat, la salida de todos ellos es la misma**: escribir en `planning/.ops-approval` las rutas que
+autorizás, una por línea, con `#` para lo que no sea una ruta. En sidecar es el `planning/` de la
+instancia y no una carpeta al lado de tus proyectos; el bloqueo dice la ruta exacta. Es un solo archivo
+para todos los guards, porque lo que escribís son rutas y quién las mira lo decide qué guard esté
+juzgando esa ruta. Lo escribís vos: si el agente intenta escribírselo, un guard lo frena.
 
 | lo que te frena | qué ruta aprobás |
 |---|---|
@@ -151,6 +161,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.