@ingeniomaps/cauce 0.78.0 → 0.80.0

package/engine/hooks/files.js

@@ -6,6 +6,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { spawnSync } = require('node:child_process')
 const {
   patchOf, filesOf, contentOf, cwdOf, block, configOf, findOpsRoot,
   writableRoots, outsideRoots, DECLARE_IT,
@@ -26,25 +27,73 @@ function opsRoot(input) {
 // el guard hasta que cierre la sesión.
 const approved = (input, file) => !AP.pending(opsRoot(input), [file]).length
 
+// Si la migración ya viajó a otra copia, que es lo que el bloqueo de abajo quiere saber y `existsSync`
+// no contesta. Devuelve el motivo del bloqueo o cadena vacía.
+//
+// **`HEAD` y no el índice**: un archivo apenas `git add`eado no viajó a ninguna parte, y `git ls-files`
+// lo daría por historial. Y **resolver la raíz es una pregunta aparte** de si el archivo está en `HEAD`:
+// las dos fallan con 128 y confundirlas repite el error que este caso arregla —decidir por la respuesta
+// equivocada—. Sin raíz resoluble se degrada a la conducta de antes, que bloquea de más, porque cuando
+// no se puede saber ése es el lado correcto para equivocarse. Es la degradación que `check` ya declara
+// cuando no puede resolver el repositorio de un servicio. Caso 086.
+function alreadyShipped(file) {
+  if (!fs.existsSync(file)) return ''
+  const cwd = path.dirname(file)
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
+  if (top.status !== 0) {
+    return 'existe, y acá no hay repositorio con el que saber si ya viajó a otra copia'
+  }
+  const rel = path.relative(top.stdout.trim(), file).split(path.sep).join('/')
+  return spawnSync('git', ['cat-file', '-e', `HEAD:${rel}`], { cwd }).status === 0
+    ? 'ya está en el historial del repositorio'
+    : ''
+}
+
+
+// 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])}`)
   }
 }
 
@@ -97,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)}`)
     }
   }
 }
@@ -126,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
@@ -152,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])}`)
   }
 }
 
@@ -230,11 +301,17 @@ 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
+    // la salida angosta, que hasta 0.79.0 sólo tenía el bloqueo hermano: éste es el que aparece en el
+    // flujo normal de escribir una migración, así que era justo el que no podía quedarse sin decirla.
     const file = path.resolve(cwdOf(input), raw)
-    if (fs.existsSync(file)) {
-      block(`${raw} es una migración existente. Crea una nueva en vez de reescribir historial.`)
+    const shipped = alreadyShipped(file)
+    if (shipped) {
+      block(`${raw} ${shipped}. Crea una nueva en vez de reescribirla.\n`
+        + AP.HOW('OPS_MIGRATIONS_OVERRIDE', [normalized]))
     }
   }
 }
@@ -265,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.78.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