@ingeniomaps/cauce 0.95.0 → 0.96.0

package/CHANGELOG.md

@@ -14,6 +14,48 @@ 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.96.0] - 2026-09-16
+
+### Corregido
+
+- **Tres errores que el CLI contestaba con exit 1 ahora contestan 2, que es lo que dice la convención.**
+  Son «no se llegó a la pregunta»: `integrations/config.json` ilegible, un proveedor que no está en ese
+  registro, y un `package.json` inválido al declarar el motor. Sus hermanos —un `ops.config.json`
+  ilegible, un proveedor que Cauce no trae— ya contestaban 2.
+
+  El corte, que hasta ahora estaba en la cabeza de quien escribía cada salida, está escrito y sale en
+  `ops --help`: **2** es que el comando no existe, falta un argumento, o la raíz que nombrás no es lo que
+  dice ser —lo arreglás cambiando la invocación—; **1** es que se llegó y la respuesta es que no —una
+  validación encontró problemas, el estado se niega, o una operación falló a mitad de camino—.
+
+  Si tenés un script que distingue los dos, revisá esos tres casos. Si sólo mira «distinto de cero», no
+  cambia nada.
+
+- **`ops flow list|check|show` acepta la raíz de la instancia, como el resto.** Todos los comandos que leen
+  una instancia la toman como posicional; `flow` la descartaba y resolvía por el directorio actual, así que
+  `ops flow list <raíz>` contestaba sobre otra cosa — y una lista de recorridos se lee igual de bien venga
+  de donde venga. Ahora es `ops flow list [ops-root]`, y con recorrido va después de él.
+
+- **Una lista de cargos o recorridos vacía dice si es porque no hay o porque no se pudo resolver el
+  paquete.** Eran dos hechos distintos con la misma respuesta, y las acciones son opuestas. El aviso sale
+  por `stderr` y sólo cuando la lista viene vacía; el código de salida y el `--json` no cambian, porque
+  ese JSON lo consume el cron del ciclo de aprendizaje.
+
+- **`automation check` nombra un `ops.config.json` ilegible en vez de culpar al motor.** La resolución del
+  paquete cuelga de esa configuración, así que un JSON roto se propagaba como archivos del motor que faltan
+  y el aviso mandaba a correr `npm install` sobre un motor instalado: la acción sugerida no arreglaba nada.
+
+- **El catálogo de cargos y recorridos se encuentra también cuando el paquete vive un nivel arriba.** Es el
+  layout que documenta el arranque —`npm install @ingeniomaps/cauce` en la carpeta de la empresa y la
+  instancia adentro—, y 0.92.0 lo arregló para el motor y dejó afuera el catálogo. En ese estado `check`
+  pasaba en verde y `agents list` contestaba **una lista vacía con exit 0**, indistinguible de «esta
+  instancia no tiene cargos»; `flow list` igual, y `evaluate` culpaba a un `SKILL.md` que falta, mandando
+  a mirar el cargo en vez del paquete.
+
+  Si te pasó, no hacía falta bajar una segunda copia: con esta versión los cargos aparecen donde ya estaban.
+  Verificado instalando el paquete publicado desde el registro y recorriendo la superficie del CLI: de 0
+  cargos y 0 recorridos a **53 y 7**, sobre la misma instancia.
+
 ## [0.95.0] - 2026-09-16
 
 ### Corregido

package/engine/automation/check.js

@@ -22,6 +22,12 @@ const { hasHooks } = require('./config')
 
 function check(root) {
   const errors = []
+  // La configuración se lee primero y se corta ahí. La resolución del paquete cuelga de ella —`declaredRoot`
+  // la parsea— así que un JSON roto se propagaba como archivos del motor que faltan, y el aviso mandaba a
+  // correr `npm install` sobre un motor que está instalado: la acción sugerida no arreglaba nada. Nombrar
+  // la causa y no seguir es lo que separa este aviso del ruido — enumerar ausencias que salen de una causa
+  // ya nombrada manda a arreglar lo que no está roto (caso 174).
+  try { O.mode(root) } catch (error) { return [error.message] }
   const hookDir = path.join(root, 'automatization', 'hooks')
   if (!fs.existsSync(path.join(root, 'automatization', 'AGENTS.md'))) {
     errors.push('falta automatization/AGENTS.md')

package/engine/cli/archive.js

@@ -11,7 +11,7 @@ const P = require('../planning/parser')
 const PC = require('../planning/contracts')
 const AD = require('../planning/adoption')
 const F = require('../core/files')
-const { fail, planningRoot, TODAY } = require('./io')
+const { fail, planningRoot, TODAY, USAGE, REFUSED } = require('./io')
 
 // El historial de acciones humanas se acumula en un solo archivo y no por épica: una fila no pertenece
 // a ninguna, y esperar el cierre de una épica dejaría sin archivar las de un planning que todavía no
@@ -30,7 +30,7 @@ function adopt(dir) {
     const existing = fs.readFileSync(target, 'utf8')
     if (!AD.sealWarnings(root).some((one) => /sin huella/.test(one))) {
       fail(`${AD.BASELINE} ya existe: se genera una vez. Para retirar un renglón, ponele \`#~\` `
-        + 'delante; `check` marca los que ya cumplen.')
+        + 'delante; `check` marca los que ya cumplen.', REFUSED)
     }
     const slugs = AD.declared(existing)
     F.atomicWrite(target, existing.replace(/\n?$/, `\n# huella: ${slugs.length} entradas · `
@@ -78,7 +78,7 @@ function archiveHumanActions(root) {
 function archive(dir, rawNum) {
   if (String(rawNum || '') === 'human-actions') return archiveHumanActions(planningRoot(dir))
   return fail('Sólo se archiva `human-actions`. La evidencia de una tarea ya vive en su propio archivo '
-    + 'de `done/`, así que archivar una épica dejó de tener sentido.', 2)
+    + 'de `done/`, así que archivar una épica dejó de tener sentido.', USAGE)
 }
 
 module.exports = { archive, adopt }

package/engine/cli/bench.js

@@ -18,7 +18,7 @@ const CL = require('../planning/claims')
 const P = require('../planning/parser')
 const IN = require('./instance')
 const O = require('../core/ownership')
-const { fail, opsRoot, TODAY } = require('./io')
+const { fail, opsRoot, TODAY, USAGE } = require('./io')
 
 // Qué decir cuando el banco sobrevivió a su propio borrado, que es lo único que va a permitir
 // establecer la causa. Devuelve el mensaje en vez de escribirlo donde ocurre, y eso es lo que lo hace
@@ -106,7 +106,7 @@ function makeBench(root, dir, force, name) {
   const dirty = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' })
   if ((dirty.stdout || '').trim() && !force) {
     fail(`${dir} tiene trabajo sin recoger. Guardá lo que esa corrida dejó antes de rehacerlo, `
-      + 'o usá --force si ya lo tenés.', 2)
+      + 'o usá --force si ya lo tenés.', USAGE)
   }
   // Rodear un borrado a medias deja la corrida siguiendo sobre un banco que no es nuevo, y lo que falla
   // después no dice nada del borrado: el test que lo destapó reportaba `true !== false` sobre un archivo
@@ -116,7 +116,7 @@ function makeBench(root, dir, force, name) {
   // **Y de acá para abajo el directorio no existe.** Eso es lo que sostiene que el andamiaje y el enlace
   // se escriban sin defensas: hasta el 073, los dos llevaban una por si algo sobrevivía al borrado.
   const problema = clearBench(dir, path.join(root, '.cauce-eval'))
-  if (problema) fail(problema, 2)
+  if (problema) fail(problema, USAGE)
   // Sin `force`, y eso es lo que hay que poder decir: sólo servía si algún archivo sobrevivía al borrado,
   // y la comprobación de arriba garantiza que no queda ninguno. Lo llevaba porque el mismo test falló tres
   // veces en un día con «El destino contiene …/AGENTS.md», y eso era el escritor de fondo que apagó el 073.
@@ -183,7 +183,7 @@ function seal(dir, git, mensaje) {
 function evaluationBench(root, agent, caso, force, kind) {
   const safe = (value) => {
     if (!/^[a-z0-9_][a-z0-9._-]*$/i.test(value) || value.includes('..')) {
-      fail(`nombre inválido para el banco: ${value}`, 2)
+      fail(`nombre inválido para el banco: ${value}`, USAGE)
     }
     return value
   }
@@ -273,7 +273,7 @@ function populate(dir, scenario, git) {
 // `clearBench` ya se niega a borrar fuera de ahí— y se distingue por el escenario, que es lo que lo puebla.
 function measurementBench(root, scenario, force) {
   if (!SCENARIOS.includes(scenario)) {
-    fail(`escenario desconocido: ${scenario || '(ninguno)'}. Hay ${SCENARIOS.join(', ')}.`, 2)
+    fail(`escenario desconocido: ${scenario || '(ninguno)'}. Hay ${SCENARIOS.join(', ')}.`, USAGE)
   }
   const dir = path.join(root, '.cauce-eval', '_medicion', scenario)
   const { env, git } = makeBench(root, dir, force, `Banco de medición (${scenario})`)
@@ -293,7 +293,7 @@ function bench(scenario, cli) {
   const root = opsRoot()
   if (O.mode(root) !== 'toolkit') {
     fail('ops bench es del toolkit: arma un banco desechable para medir a Cauce. En una instancia, lo '
-      + 'que se mide es tu propio proyecto — corré el comando que quieras medir sobre tu planning/.', 2)
+      + 'que se mide es tu propio proyecto — corré el comando que quieras medir sobre tu planning/.', USAGE)
   }
   const dir = measurementBench(root, scenario, cli.has('--force'))
   console.log(path.relative(root, dir))

package/engine/cli/catalog.js

@@ -13,14 +13,14 @@ const O = require('../core/ownership')
 // El banco desechable y su borrado comprobado. Se reexportan abajo porque su contrato lo fija la suite
 // del banco, que llega por acá desde antes de que el módulo existiera.
 const B = require('./bench')
-const { fail, opsRoot, TODAY } = require('./io')
+const { fail, opsRoot, TODAY, USAGE, REFUSED } = require('./io')
 
 function agentsFork(slug, dir) {
   const root = opsRoot(dir)
-  if (!slug) fail('Falta el cargo: ops agents fork <cargo> [ops-root]', 2)
+  if (!slug) fail('Falta el cargo: ops agents fork <cargo> [ops-root]', USAGE)
   let result
   const date = TODAY()
-  try { result = require('../agents/fork').fork(root, slug, date) } catch (error) { fail(error.message, 2) }
+  try { result = require('../agents/fork').fork(root, slug, date) } catch (error) { fail(error.message, USAGE) }
   console.log(`+ ${path.relative(root, result.dir)} (${result.files.length} archivo(s))`)
   if (result.skipped.length) {
     console.log(`  quedan en el catálogo: ${result.skipped.length} artefacto(s) que ganó su versión`)
@@ -31,15 +31,28 @@ function agentsFork(slug, dir) {
 
 // Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
 // reimplemente el recorrido del catálogo.
+// Una lista vacía y un paquete que no se resolvió se ven igual, y las acciones son opuestas: en uno no hay
+// nada que hacer, en el otro falta una instalación. Se avisa sólo cuando la lista sale vacía, que es cuando
+// la ambigüedad existe — con resultados a la vista no hay nada que aclarar.
+//
+// Va por `stderr` y no por el código de salida: el `--json` lo consume el cron del ciclo de aprendizaje, y
+// romperle el contrato para arreglar un mensaje sería cambiar lo que no está mal (caso 173).
+function warnUnresolved(root, name, found) {
+  if (found || O.packageDir(root, name)) return
+  console.error(`⚠ ${name}/ no se pudo resolver desde ${root}: el paquete @ingeniomaps/cauce no está ahí `
+    + `ni en la raíz que declara ops.config.json, así que una lista vacía acá no dice que no haya ${name}.`)
+}
+
 function agents(action, dir, extra, cli) {
   if (action === 'fork') return agentsFork(dir, extra)
-  if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
+  if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, USAGE)
   const root = opsRoot(dir)
   // Una empresa mantiene sus cargos, no los nuestros: `learn` sobre uno del catálogo se niega, así que
   // recorrer el catálogo entero para encontrar el suyo es ruido. `--own` hace ejecutable ese recorrido.
   const own = cli.has('--own')
   const system = cli.has('--system')
   const roles = AG.list(root).filter((role) => (own ? !role.system : true) && (system ? role.system : true))
+  warnUnresolved(root, 'agents', roles.length)
   if (cli.has('--json')) {
     // `path` viene resuelto: quien consuma esto no debería reconstruir dónde ganó la precedencia.
     return console.log(JSON.stringify(roles.map((role) => ({
@@ -104,7 +117,7 @@ function learn(agent, cli) {
     // falta. Negarse nombrando el comando que sí corresponde es lo que cierra R13.
     if (kind === 'flow' && !cli.has('--proposal')) {
       fail(`${agent} es un recorrido: aprende de sus corridas, no de informes semanales.\n`
-        + `  Abrí la propuesta con "ops learn ${agent} --flow --proposal".`, 2)
+        + `  Abrí la propuesta con "ops learn ${agent} --flow --proposal".`, USAGE)
     }
     // `--period` es para consolidar a mano un mes que no es el de hoy. El ciclo automático no lo
     // pasa: la propuesta se llama por el mes en que se abre y arrastra lo que todavía no entró.
@@ -133,7 +146,7 @@ function learn(agent, cli) {
     if (LF.blankProposal(result.file)) {
       console.log('  sin cambio decidido: falta correr agent-propose antes de que esto se pueda firmar')
     }
-  } catch (error) { fail(error.message, 2) }
+  } catch (error) { fail(error.message, USAGE) }
 }
 
 function evaluate(agent, caso, cli) {
@@ -149,7 +162,7 @@ function evaluate(agent, caso, cli) {
       // forkeaba, repetía el comando y recibía el mismo mensaje diciéndole que forkeara—.
       fail('--bench es del toolkit. En una instancia, el cargo trabaja sobre tu planning/: corré '
         + `"ops evaluate ${agent}" sin la bandera, que valida sus controles, casos y propuestas `
-        + 'contra este proyecto.', 2)
+        + 'contra este proyecto.', USAGE)
     }
     // El caso es el posicional que sigue al cargo: `evaluate <cargo> --bench <caso>`. Sin él se arma
     // un banco suelto, para mirarlo a mano; una corrida real pide uno por caso.
@@ -190,7 +203,7 @@ function evaluate(agent, caso, cli) {
     const errors = [...result.errors, ...runs.errors]
     for (const warning of [...result.warnings, ...runs.warnings]) console.warn(`⚠ ${warning}`)
     for (const error of errors) console.error(`✗ ${error}`)
-    if (errors.length) fail(`\n${errors.length} error(es)`, 1)
+    if (errors.length) fail(`\n${errors.length} error(es)`, 1, REFUSED)
     // Cuándo se midió es un rango cuando el veredicto vigente lo aportó más de una corrida. Por qué se
     // compone en vez de leerse la última, en `composed`.
     const measuredAt = runs.state && runs.state.oldest !== runs.state.newest
@@ -208,13 +221,19 @@ function evaluate(agent, caso, cli) {
         `${result.pending ? ` (${result.pending} sin aplicar)` : ''}, ` +
         'controles estructurales válidos',
     )
-  } catch (error) { fail(error.message, 2) }
+  } catch (error) { fail(error.message, USAGE) }
 }
 
-function flow(action, slug, cli) {
+// La raíz la toma como posicional, igual que el resto de los comandos que leen una instancia: `list` no
+// lleva recorrido, así que la suya es el primer posicional, y `check`/`show` la llevan después del
+// recorrido —la misma forma que `agents fork <cargo> [ops-root]`—. Antes se descartaba y todo resolvía por
+// `opsRoot()`, así que `ops flow list <raíz>` contestaba sobre el directorio actual y la respuesta se leía
+// igual de bien viniendo de otra instancia (caso 172).
+function flow(action, slug, dir, cli) {
+  const root = opsRoot(action === 'list' ? slug : dir)
   if (action === 'list') {
-    const root = opsRoot()
     const slugs = T.list(root)
+    warnUnresolved(root, 'flows', slugs.length)
     // La misma forma que `agents list --json`, porque la consume el mismo cron. `cadence` es fija:
     // un recorrido no tiene profesión que cambie afuera, así que su calendario no se deriva de
     // fuentes —no tiene—; lo que decide si le toca es `pending`, las corridas que dejó sin consolidar.
@@ -238,11 +257,11 @@ function flow(action, slug, cli) {
     for (const name of slugs) console.log(name)
     return
   }
-  if (!['check', 'show'].includes(action)) fail(`Acción de flow desconocida: ${action || '(vacía)'}`, 2)
+  if (!['check', 'show'].includes(action)) fail(`Acción de flow desconocida: ${action || '(vacía)'}`, USAGE)
   try {
-    const result = T.validate(opsRoot(), slug)
+    const result = T.validate(root, slug)
     for (const error of result.errors) console.error(`✗ ${error}`)
-    if (result.errors.length) fail(`${slug}: ${result.errors.length} error(es)`, 1)
+    if (result.errors.length) fail(`${slug}: ${result.errors.length} error(es)`, 1, REFUSED)
     if (action === 'show') {
       // El manifiesto entero, para que un workflow ejecute las etapas sin que un modelo lo parsee.
       if (cli.has('--json')) return console.log(JSON.stringify(result.manifest))
@@ -254,7 +273,7 @@ function flow(action, slug, cli) {
     } else {
       console.log(`✓ ${slug}: ${result.stages} etapa(s), ${result.agents} agente(s), contrato válido`)
     }
-  } catch (error) { fail(error.message, 2) }
+  } catch (error) { fail(error.message, USAGE) }
 }
 
 module.exports = {

package/engine/cli/claims.js

@@ -9,25 +9,25 @@ const path = require('node:path')
 const CL = require('../planning/claims')
 const R = require('../core/repos')
 const ST = require('../planning/state')
-const { fail, planningRoot, TODAY } = require('./io')
+const { fail, planningRoot, TODAY, USAGE, REFUSED } = require('./io')
 
 function claim(dir, slug, cli) {
   const root = planningRoot(dir)
-  if (!slug) return fail('Falta el slug. `ops claim <planning-dir> <tarea>`', 2)
+  if (!slug) return fail('Falta el slug. `ops claim <planning-dir> <tarea>`', USAGE)
   const state = ST.snapshot(root)
   const task = state.milestones.flatMap((milestone) => milestone.tasks).find((one) => one.slug === slug)
-  if (!task) return fail(`${slug} no está en BACKLOG: sólo se toma trabajo ya promovido.`, 2)
+  if (!task) return fail(`${slug} no está en BACKLOG: sólo se toma trabajo ya promovido.`, USAGE)
 
   // No se reserva lo que todavía no se puede empezar: una tarea tomada con su dependencia en vuelo
   // bloquea la cola sin que nadie pueda avanzarla, y el runner que la tomó se queda sin poder tomar otra.
   const blocker = task.depends.find((dep) => !state.done.set.has(dep))
-  if (blocker) return fail(`${slug} depende de ${blocker}, que todavía no está en DONE.`)
+  if (blocker) return fail(`${slug} depende de ${blocker}, que todavía no está en DONE.`, REFUSED)
 
   const me = CL.owner(root)
   const from = CL.runner()
   if (!me) {
     return fail('No sé quién sos. Configurá `git config user.email` o exportá CAUCE_OWNER: '
-      + 'un reclamo anónimo no dice a quién preguntarle.', 2)
+      + 'un reclamo anónimo no dice a quién preguntarle.', USAGE)
   }
   // Un runner lleva una tarea a la vez (BR-OPS-001), y exigirlo acá hace ruidosa la única forma en que
   // este contrato falla en silencio: dos agentes de la misma máquina compartiendo id porque nadie puso
@@ -38,7 +38,7 @@ function claim(dir, slug, cli) {
     .find((one) => one.runner === from && one.slug !== slug && !state.done.set.has(one.slug))
   if (ocupado) {
     return fail(`este runner ya tiene ${ocupado.slug}. Cerrala o soltala primero; y si sos otro agente `
-      + 'en la misma máquina, exportá CAUCE_RUNNER con un valor propio.')
+      + 'en la misma máquina, exportá CAUCE_RUNNER con un valor propio.', REFUSED)
   }
 
   const target = CL.file(root, slug)
@@ -58,7 +58,7 @@ function claim(dir, slug, cli) {
     const holder = CL.read(root).find((one) => one.slug === slug)
     // Existía al crear y ya no está: alguien la soltó entre las dos operaciones. Es una ventana de
     // microsegundos y aun así tiene respuesta, porque la alternativa es reventar con un TypeError.
-    if (!holder) return fail(`${slug} cambió de manos mientras la pedías; volvé a intentarlo.`)
+    if (!holder) return fail(`${slug} cambió de manos mientras la pedías; volvé a intentarlo.`, REFUSED)
     if (holder.runner === from) return console.log(`= ${slug} ya era tuya desde ${holder.started}`)
     // Mismo dueño y otro runner son dos situaciones que se ven idénticas desde acá —vos retomando la
     // sesión de ayer, o un segundo agente tuyo— y ninguna se puede distinguir mirando el archivo.
@@ -68,10 +68,10 @@ function claim(dir, slug, cli) {
       return fail(`${slug} la tenés vos, tomada el ${holder.started} desde el runner ${holder.runner}. `
         + 'Preguntá si se retoma esa sesión —y entonces corré con ese id— o si es otro agente en '
         + `paralelo, que toma otra tarea. \`ops runners ${path.relative(process.cwd(), root) || '.'}\` `
-        + 'lista lo que hay abierto.')
+        + 'lista lo que hay abierto.', REFUSED)
     }
     return fail(`${slug} la tomó ${holder.owner} el ${holder.started}. Si se abandonó, borrá `
-      + `${CL.DIR}/${slug}.md a mano: soltar lo de otro es una decisión, no un comando.`)
+      + `${CL.DIR}/${slug}.md a mano: soltar lo de otro es una decisión, no un comando.`, REFUSED)
   }
   console.log(`✓ ${slug} tomada por ${me}`)
   if (!cli.has('--json')) {
@@ -87,12 +87,12 @@ function claim(dir, slug, cli) {
 
 function release(dir, slug) {
   const root = planningRoot(dir)
-  if (!slug) return fail('Falta el slug. `ops release <planning-dir> <tarea>`', 2)
+  if (!slug) return fail('Falta el slug. `ops release <planning-dir> <tarea>`', USAGE)
   const from = CL.runner()
   const taken = CL.read(root).find((one) => one.slug === slug)
-  if (!taken) return fail(`${slug} no está tomada por nadie.`, 2)
+  if (!taken) return fail(`${slug} no está tomada por nadie.`, USAGE)
   if (taken.runner !== from) {
-    return fail(`${slug} es de ${taken.owner}. Si se abandonó, borrá ${taken.at} a mano.`)
+    return fail(`${slug} es de ${taken.owner}. Si se abandonó, borrá ${taken.at} a mano.`, REFUSED)
   }
   fs.rmSync(CL.file(root, slug))
   console.log(`✓ ${slug} soltada; volvió a la cola`)

package/engine/cli/contract.js

@@ -15,7 +15,7 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const P = require('../planning/parser')
-const { fail, opsRoot } = require('./io')
+const { fail, opsRoot, USAGE } = require('./io')
 
 // Los cuatro que componen el contrato, con la ruta relativa a la raíz de la instancia. El orden es el que
 // usa el mensaje de error: se nombra el primero que falte y no los cuatro, porque arreglar uno suele
@@ -188,14 +188,15 @@ function contract(dir, cli) {
   // se pierde no se ve en la salida, se ve tres fases después en lo que un subagente creyó que podía tocar.
   if (missing) {
     return fail(`${root} no tiene ${missing}, así que no hay contrato que derivar. Es la raíz que escribió `
-      + '`automation install`: comprobá que exista y, si moviste el proyecto de carpeta, reinstalá el adaptador.', 2)
+      + '`automation install`: comprobá que exista y, si moviste el proyecto de carpeta, reinstalá el adaptador.',
+    USAGE)
   }
 
   let config
   try {
     config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   } catch (error) {
-    return fail(`ops.config.json no se pudo leer como JSON: ${error.message}`, 2)
+    return fail(`ops.config.json no se pudo leer como JSON: ${error.message}`, USAGE)
   }
 
   const sections = {}
@@ -205,7 +206,7 @@ function contract(dir, cli) {
     // que poder abrir el archivo y ver qué encabezado falta, y el arreglo es restaurarlo con `upgrade`.
     if (!found.trim()) {
       return fail(`${file} no tiene la sección ${name}, y de ahí sale el contrato que reciben los agentes. `
-        + 'Ese archivo lo reemplaza `ops upgrade` entero: corrélo para restaurarlo.', 2)
+        + 'Ese archivo lo reemplaza `ops upgrade` entero: corrélo para restaurarlo.', USAGE)
     }
     sections[file] = found
   }

package/engine/cli/dependency.js

@@ -7,7 +7,7 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const F = require('../core/files')
-const { fail } = require('./io')
+const { fail, USAGE } = require('./io')
 
 // Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
 // Conserva el manifiesto existente porque el repo anfitrión puede tener el suyo.
@@ -15,7 +15,7 @@ function declareEngine(manifest, version) {
   let pkg = { name: path.basename(path.dirname(manifest)), private: true, version: '0.0.0' }
   if (fs.existsSync(manifest)) {
     try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch (error) {
-      fail(`package.json inválido en ${manifest}: ${error.message}`)
+      fail(`package.json inválido en ${manifest}: ${error.message}`, USAGE)
     }
   }
   pkg.devDependencies = { ...pkg.devDependencies, '@ingeniomaps/cauce': version }

package/engine/cli/instance.js

@@ -15,7 +15,7 @@ const P = require('../planning/parser')
 const ST = require('../planning/state')
 const RC = require('../planning/recurring')
 const A = require('../automation')
-const { fail, TODAY } = require('./io')
+const { fail, TODAY, USAGE, REFUSED } = require('./io')
 const { declareEngine, pinEngine, undeclareEngine } = require('./dependency')
 const { adviceFor, previewUpgrade, reportUpgrade } = require('./upgrade-report')
 
@@ -47,7 +47,7 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
     if (entry.isDirectory()) Object.assign(preserved, copyTemplate(from, to, replacements, force, skip, quiet))
     else {
       if (fs.existsSync(to)) {
-        if (!force) fail(`El destino contiene ${to}. Usa un directorio vacío o --force.`)
+        if (!force) fail(`El destino contiene ${to}. Usa un directorio vacío o --force.`, REFUSED)
         if (!quiet) console.log(`= conservado ${to}`)
         let would = fs.readFileSync(from, 'utf8')
         for (const [key, value] of Object.entries(replacements)) would = would.replaceAll(key, value)
@@ -175,9 +175,9 @@ function whatIsLost(root) {
 function destroy(dir, cli) {
   const root = path.resolve(dir || '.')
   if (!fs.existsSync(path.join(root, 'ops.config.json'))) {
-    fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, 2)
+    fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, USAGE)
   }
-  if (O.mode(root) === 'toolkit') fail(`${root} es el toolkit: acá se fabrica Cauce, no se lo borra.`, 2)
+  if (O.mode(root) === 'toolkit') fail(`${root} es el toolkit: acá se fabrica Cauce, no se lo borra.`, USAGE)
 
   const loss = whatIsLost(root)
   const lines = [
@@ -261,12 +261,12 @@ function renameTeamsToFlows(root) {
 function upgrade(dir, cli) {
   const root = path.resolve(dir || '.')
   if (!fs.existsSync(path.join(root, 'ops.config.json'))) {
-    fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, 2)
+    fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, USAGE)
   }
   // Acá se fabrica Cauce: `upgrade` reemplazaría con las copias de `template/` los archivos que este
   // repositorio mantiene en la raíz —`AGENTS.md` entre ellos, que es donde vive esta misma regla—.
   if (O.mode(root) === 'toolkit') {
-    fail(`${root} es el toolkit: acá se edita Cauce, no se lo actualiza.`, 2)
+    fail(`${root} es el toolkit: acá se edita Cauce, no se lo actualiza.`, USAGE)
   }
   // Antes que nada, y antes de los controles: `teams/` pasó a llamarse `flows/`, y los controles que
   // siguen miran las rutas nuevas. Sin esto `upgrade` copiaría `flows/` al lado y dejaría los
@@ -299,6 +299,7 @@ function upgrade(dir, cli) {
     fail(
       `\n${rescue.length} archivo(s) de aprendizaje quedaron en una ruta que Cauce ya no mantiene.\n\n` +
       'Movelos a un cargo propio en agents/roles/<slug>/learning/ y repetí, o descartalos con --force.',
+      REFUSED,
     )
   }
 

package/engine/cli/io.js

@@ -3,9 +3,31 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
+// Los dos códigos con que termina el CLI, y el corte entre ellos. Están nombrados porque el número suelto
+// no dice de qué lado cae: un «2» y un argumento ausente se leen igual de arbitrarios, así que cada sitio
+// nuevo elegía por imitación del vecino y tres terminaron del lado equivocado.
+//
+//   USAGE   — no se llegó a la pregunta. El comando no existe, le falta un argumento, o la raíz que
+//             nombra no es lo que dice ser. Lo arregla quien invoca, cambiando la invocación.
+//   REFUSED — se llegó, y la respuesta es que no. Cubre tres formas y ninguna pide otro código: una
+//             validación encontró problemas, el estado se niega, o una operación falló a mitad de camino.
+//             La invocación estaba bien; lo que hay que mirar es el proyecto.
+//
+// La distinción se gana lo que cuesta porque afuera ya se la necesitaba sin tenerla: la parada
+// `claim-stuck` de `autobuild` separa dos defectos leyendo el **texto** de lo que `claim` contestó, y por
+// qué tiene que distinguirlos está ahí. Uno de los dos es exactamente USAGE.
+//
+// Un tercero no hace falta y costaría: las tres formas de REFUSED terminan igual para quien scriptea
+// —mirá el proyecto—, y separarlas obligaría a conocer el reparto para hacer lo mismo con las tres.
+const USAGE = 2
+const REFUSED = 1
+
 // Terminar la corrida con un mensaje y un código. Vive aparte porque lo usa cada familia de comandos, y
 // dejarlo en el despacho obligaría a que cada módulo dependa del que lo invoca.
-function fail(message, code = 1) {
+//
+// El default se queda siendo REFUSED aunque la puerta exija que cada sitio diga el suyo: es el piso
+// seguro —distinto de cero— para un llamador que la puerta todavía no mire.
+function fail(message, code = REFUSED) {
   console.error(message)
   process.exit(code)
 }
@@ -40,14 +62,14 @@ function opsRoot(dir) {
 function planningRoot(dir) {
   const root = path.resolve(dir || '.')
   if (!fs.existsSync(root)) {
-    return fail(`no existe el planning en ${root} (ruta resuelta). Comprobá desde dónde estás invocando.`, 2)
+    return fail(`no existe el planning en ${root} (ruta resuelta). Comprobá desde dónde estás invocando.`, USAGE)
   }
   // Existir no alcanza: un directorio cualquiera contestaría cola vacía igual. `BACKLOG.md` es el archivo
   // del que sale la cola, así que sin él la respuesta no significa nada.
   if (!fs.existsSync(path.join(root, 'BACKLOG.md'))) {
-    return fail(`${root} (ruta resuelta) no es un planning: falta BACKLOG.md.`, 2)
+    return fail(`${root} (ruta resuelta) no es un planning: falta BACKLOG.md.`, USAGE)
   }
   return root
 }
 
-module.exports = { fail, opsRoot, planningRoot, TODAY }
+module.exports = { fail, opsRoot, planningRoot, TODAY, USAGE, REFUSED }

package/engine/cli/ops.js

@@ -6,7 +6,7 @@ const path = require('node:path')
 const { spawnSync } = require('node:child_process')
 const A = require('../automation')
 const { FLAGS, parse } = require('./args')
-const { fail } = require('./io')
+const { fail, USAGE, REFUSED } = require('./io')
 const IN = require('./instance')
 const PL = require('./planning')
 const CT = require('./contract')
@@ -88,7 +88,7 @@ async function init(target, cli) {
   // directorio y elegían modos opuestos, así que escribir el punto daba el layout contrario al de
   // arriba sin que nadie lo pidiera.
   const mode = cli.value('--mode', isInstanceDir(root) ? 'sidecar' : 'embedded')
-  if (!['embedded', 'sidecar'].includes(mode)) fail('--mode debe ser embedded o sidecar.', 2)
+  if (!['embedded', 'sidecar'].includes(mode)) fail('--mode debe ser embedded o sidecar.', USAGE)
   const name = cli.value('--name', defaultName(root))
   const force = cli.has('--force')
   // `.git` no cuenta como contenido: es lo único que hay en la carpeta que alguien acaba de crear y
@@ -96,7 +96,7 @@ async function init(target, cli) {
   // más natural —`mkdir acme-ops && git init && cauce init`— pedía `--force` para no pisar nada.
   const existing = (fs.existsSync(root) ? fs.readdirSync(root) : []).filter((entry) => entry !== '.git')
   if (existing.length && !force) {
-    fail(`El destino no está vacío: ${root}. Usa --force para agregar solo archivos faltantes.`)
+    fail(`El destino no está vacío: ${root}. Usa --force para agregar solo archivos faltantes.`, REFUSED)
   }
   // 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—
@@ -112,7 +112,7 @@ async function init(target, cli) {
   }
   // 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) }
+  try { BOOT.validate(options) } catch (error) { fail(error.message, USAGE) }
   IN.scaffold(root, { name, mode, force })
   const relative = path.relative(process.cwd(), root)
   const enter = relative && relative !== '.' ? `cd ${relative} && ` : ''
@@ -125,7 +125,7 @@ async function init(target, cli) {
       installRunner: (runner) => W.automation('install', root, runner, NO_FLAGS),
       enableProvider: (provider) => W.enableProvider(root, provider),
     })
-  } catch (error) { fail(error.message, 2) }
+  } catch (error) { fail(error.message, USAGE) }
 
   if (result.installed) VA.check(path.join(root, 'planning'), NO_FLAGS)
 
@@ -139,7 +139,7 @@ async function init(target, cli) {
   console.log('')
   W.onboard(root, NO_FLAGS, result.installed ? result.runner : '')
   for (const step of initSteps(enter, result)) console.log(step)
-  if (result.error) fail(`${result.error}: la instancia quedó creada pero todavía no funciona.`)
+  if (result.error) fail(`${result.error}: la instancia quedó creada pero todavía no funciona.`, REFUSED)
 }
 
 function usage() {
@@ -184,9 +184,14 @@ function usage() {
   ops evaluate <agent|flow> [--flow] [--cases [--json]] [--bench [caso]] [--record [AAAA-MM-DD]]
   ops agents list [ops-root] [--own|--system] [--json]
   ops agents fork <cargo> [ops-root]
-  ops flow list
-  ops flow check <flow>
-  ops flow show <flow>`)
+  ops flow list [ops-root]
+  ops flow check <flow> [ops-root]
+  ops flow show <flow> [ops-root]
+
+Códigos de salida:
+  2  no se llegó a la pregunta: el comando no existe, falta un argumento, o la raíz no es lo que dice ser.
+  1  se llegó y la respuesta es que no: una validación encontró problemas, el estado se niega, o una
+     operación falló a mitad de camino.`)
 }
 
 // Un `cli` que no tiene banderas, para reusar un comando desde otro: el `--force` de `init` habla del
@@ -200,14 +205,14 @@ async function run(cli) {
   if (!command || command === 'help') return usage()
   // `Object.hasOwn` y no `FLAGS[command]`: `constructor` heredado de `Object.prototype` pasaba por
   // comando válido y el CLI salía con 0 sin hacer nada.
-  if (!Object.hasOwn(FLAGS, command)) { usage(); fail(`Comando desconocido: ${command}`, 2) }
+  if (!Object.hasOwn(FLAGS, command)) { usage(); fail(`Comando desconocido: ${command}`, USAGE) }
   // `--help` valía sólo como primer argumento: `check --help` corría `check` contra el directorio
   // actual en vez de explicarse.
   if (cli.has('--help')) return usage()
   const unknown = cli.unknown(command)
   if (unknown.length) {
     const accepts = FLAGS[command].length ? `Acepta: ${FLAGS[command].join(', ')}.` : 'No acepta banderas.'
-    fail(`${command}: bandera desconocida ${unknown.join(', ')}. ${accepts}`, 2)
+    fail(`${command}: bandera desconocida ${unknown.join(', ')}. ${accepts}`, USAGE)
   }
   const arg = cli.positional
   if (command === 'init') await init(arg[1], cli)
@@ -236,7 +241,7 @@ async function run(cli) {
   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)
-  else if (command === 'flow') CAT.flow(arg[1], arg[2], cli)
+  else if (command === 'flow') CAT.flow(arg[1], arg[2], arg[3], cli)
 }
 
-run(parse(process.argv.slice(2))).catch((error) => fail(error.message))
+run(parse(process.argv.slice(2))).catch((error) => fail(error.message, REFUSED))

package/engine/cli/planning.js

@@ -14,7 +14,7 @@ const CL = require('../planning/claims')
 const ST = require('../planning/state')
 const O = require('../core/ownership')
 const EV = require('../core/evidence')
-const { fail, planningRoot, TODAY } = require('./io')
+const { fail, planningRoot, TODAY, USAGE } = require('./io')
 
 // Qué dimensiones enumera el molde de `organization/` y cuáles dejaron de estar. Un agente que reescribe
 // esos archivos tiende a quedarse con el contenido y perder la estructura: el resultado se lee entero y
@@ -34,7 +34,7 @@ function evidence(dir, cli) {
   // Sin `--task`, la más reciente, y la decide `fecha:` — por qué ese campo existe lo dice el contrato.
   const reciente = [...entries].sort((a, b) => (a.fecha || '').localeCompare(b.fecha || '')).pop()
   const entry = slug ? entries.find((one) => one.slug === slug) : reciente
-  if (!entry) return fail(slug ? `DONE no tiene la entrada ${slug}` : 'DONE no tiene ninguna entrada', 2)
+  if (!entry) return fail(slug ? `DONE no tiene la entrada ${slug}` : 'DONE no tiene ninguna entrada', USAGE)
 
   let config = {}
   try { config = JSON.parse(fs.readFileSync(path.join(opsDir, 'ops.config.json'), 'utf8')) } catch { /* sin raíces */ }
@@ -148,7 +148,7 @@ function context(dir, cli) {
     // Un hito mal escrito devolvería «sin tarea disponible», que es indistinguible de un hito terminado.
     if (!existe) {
       const hay = state.milestones.map((one) => one.slug).join(', ') || '(ninguno)'
-      return fail(`el hito ${hito} no existe. Hay: ${hay}`, 2)
+      return fail(`el hito ${hito} no existe. Hay: ${hay}`, USAGE)
     }
     if (own) hitoOmitido = `${hito} no se aplica: ya tenés ${own.slug} tomada`
     else state.milestones = state.milestones.filter((one) => one.slug === hito)
@@ -299,7 +299,7 @@ function recurring(dir, cli) {
   const promote = cli.value('--promote')
   if (promote) {
     const one = state.find((candidate) => candidate.id === promote)
-    if (!one) return fail(`${RC.FILE} no declara ${promote}`, 2)
+    if (!one) return fail(`${RC.FILE} no declara ${promote}`, USAGE)
     // La línea sale sola por stdout para que se pueda pegar o redirigir sin recortar nada; el destino,
     // que es lo único que falta decidir, va por stderr.
     console.error(`Pegala en el hito que corresponda de BACKLOG.md:`)

package/engine/cli/validate.js

@@ -30,7 +30,7 @@ const CP = require('../config/paths')
 const AG = require('../agents/catalog')
 const RL = require('../automation/rules')
 const CT = require('./contract')
-const { fail, planningRoot, TODAY } = require('./io')
+const { fail, planningRoot, TODAY, REFUSED } = require('./io')
 
 function check(dir, cli) {
   const root = planningRoot(dir)
@@ -197,7 +197,7 @@ function check(dir, cli) {
 
   for (const warning of warnings) console.warn(`⚠ ${warning}`)
   for (const error of errors) console.error(`✗ ${error}`)
-  if (errors.length) fail(`\n${errors.length} error(es), ${warnings.length} advertencia(s)`)
+  if (errors.length) fail(`\n${errors.length} error(es), ${warnings.length} advertencia(s)`, REFUSED)
   console.log(
     `✓ planning válido: ${epics.length} épica(s), ${backlog.length} tarea(s) en cola, ` +
       `${done.entries.length} terminada(s)`,

package/engine/cli/wiring.js

@@ -14,7 +14,7 @@ const SC = require('../core/scan')
 const OB = require('../core/onboarding')
 const IN = require('./instance')
 const ST = require('../planning/state')
-const { fail, opsRoot } = require('./io')
+const { fail, opsRoot, USAGE, REFUSED } = require('./io')
 
 // Cuántos servicios se listan en pantalla antes de recortar. El resto sigue en `--json`, que es lo que
 // consume el recorrido de arranque: recortar la lista es para leerla, no para acotar lo que se sabe.
@@ -45,7 +45,7 @@ const INTEGRATION = {
         && 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)
+          + `registra en integrations/config.json con "adapter": "./adapter.js"; con eso, enable lo conecta.`, USAGE)
       }
       // 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.
@@ -86,7 +86,7 @@ const INTEGRATION = {
       const result = I.validate(root, provider || '')
       for (const warning of result.warnings) console.warn(`⚠ ${warning}`)
       for (const error of result.errors) console.error(`✗ ${error}`)
-      if (result.errors.length) fail(`${result.errors.length} error(es) de integración`)
+      if (result.errors.length) fail(`${result.errors.length} error(es) de integración`, REFUSED)
       console.log(`✓ integraciones válidas${provider ? `: ${provider}` : ''}`)
     },
   },
@@ -203,14 +203,14 @@ function onboard(rootArg, cli, runner = '') {
 function providerRegistry(root) {
   const file = path.join(root, 'integrations', 'config.json')
   try { return { file, config: JSON.parse(fs.readFileSync(file, 'utf8')) } } catch (error) {
-    return fail(`integrations/config.json ilegible: ${error.message}`)
+    return fail(`integrations/config.json ilegible: ${error.message}`, USAGE)
   }
 }
 
 function switchProvider(root, provider, enabled) {
   const { file, config } = providerRegistry(root)
   if (!config.providers || !config.providers[provider]) {
-    fail(`${provider} no está en integrations/config.json.`)
+    fail(`${provider} no está en integrations/config.json.`, USAGE)
   }
   config.providers[provider].enabled = enabled
   F.atomicWriteJson(file, config)
@@ -218,8 +218,8 @@ function switchProvider(root, provider, enabled) {
 
 async function integration(action, rootArg, provider, key, cli) {
   const step = INTEGRATION[action]
-  if (!step) fail(`Acción de integración desconocida: ${action || '(vacía)'}`, 2)
-  if (step.missing && (!provider || (step.needsKey && !key))) fail(step.missing, 2)
+  if (!step) fail(`Acción de integración desconocida: ${action || '(vacía)'}`, USAGE)
+  if (step.missing && (!provider || (step.needsKey && !key))) fail(step.missing, USAGE)
   await step.run(path.resolve(rootArg || '.'), provider, key, cli)
 }
 
@@ -245,7 +245,7 @@ function automation(action, rootArg, runnerName, cli) {
   if (action === 'check') {
     const errors = A.check(root)
     for (const error of errors) console.error(`✗ ${error}`)
-    if (errors.length) fail(`${errors.length} error(es) de automatización`)
+    if (errors.length) fail(`${errors.length} error(es) de automatización`, REFUSED)
     console.log(
       `✓ automatización válida: ${A.GUARD_NAMES.length} guards, ${A.RUNNER_NAMES.length} adaptadores`,
     )
@@ -260,22 +260,22 @@ function automation(action, rootArg, runnerName, cli) {
   }
   if (action === 'doctor') {
     let result
-    try { result = A.doctor(root, runnerName) } catch (error) { fail(error.message, 2) }
+    try { result = A.doctor(root, runnerName) } catch (error) { fail(error.message, USAGE) }
     if (result.errors.length) {
-      fail(`${runnerName}: ${result.errors.length} error(es), ${result.warnings.length} advertencia(s)`)
+      fail(`${runnerName}: ${result.errors.length} error(es), ${result.warnings.length} advertencia(s)`, REFUSED)
     }
     console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
     return
   }
   if (action === 'uninstall') {
-    try { A.uninstall(root, runnerName, console) } catch (error) { fail(error.message, 2) }
+    try { A.uninstall(root, runnerName, console) } catch (error) { fail(error.message, USAGE) }
     console.log('  la instancia sigue en pie: borrar la carpeta ops es una decisión aparte.')
     return
   }
   if (action === 'install') {
     let runner
     const force = cli.has('--force')
-    try { runner = A.install(root, runnerName, console, { force }) } catch (error) { fail(error.message, 2) }
+    try { runner = A.install(root, runnerName, console, { force }) } catch (error) { fail(error.message, USAGE) }
     if (runnerName === 'codex') {
       console.log('  Codex deja los hooks nuevos sin correr hasta que los confíes: abrí una sesión')
       console.log('  y usá /hooks para revisarlos y marcarlos como confiables.')
@@ -284,20 +284,20 @@ function automation(action, rootArg, runnerName, cli) {
       console.log(`  ${runnerName} no expone hooks nativos; aplica guards como prechecks.`)
     }
     const result = A.doctor(root, runnerName)
-    if (result.errors.length) fail(`${runnerName}: instalación incompleta`)
+    if (result.errors.length) fail(`${runnerName}: instalación incompleta`, REFUSED)
     console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
     return
   }
-  fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, 2)
+  fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, USAGE)
 }
 
 function secrets(action, rootArg) {
-  if (action !== 'check') fail(`Acción de secretos desconocida: ${action || '(vacía)'}`, 2)
+  if (action !== 'check') fail(`Acción de secretos desconocida: ${action || '(vacía)'}`, USAGE)
   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`)
+  if (result.errors.length) fail(`${result.errors.length} error(es) en el contrato de secretos`, REFUSED)
   console.log(`✓ contrato de secretos: ${result.current} servicio(s) al día`)
 }
 

package/engine/cli/worktree.js

@@ -15,7 +15,7 @@ const ST = require('../planning/state')
 const CL = require('../planning/claims')
 const R = require('../core/repos')
 const O = require('../core/ownership')
-const { fail, planningRoot } = require('./io')
+const { fail, planningRoot, USAGE, REFUSED } = require('./io')
 
 const git = (cwd, ...args) => spawnSync('git', args, { cwd, encoding: 'utf8' })
 
@@ -34,38 +34,38 @@ function existing(repo, branch) {
 
 function worktree(dir, slug, cli) {
   const root = planningRoot(dir)
-  if (!slug) return fail('Falta el slug. `ops worktree <planning-dir> <tarea>`', 2)
+  if (!slug) return fail('Falta el slug. `ops worktree <planning-dir> <tarea>`', USAGE)
   const state = ST.snapshot(root)
   const task = state.milestones.flatMap((milestone) => milestone.tasks).find((one) => one.slug === slug)
-  if (!task) return fail(`${slug} no está en BACKLOG: sólo se prepara trabajo ya promovido.`, 2)
+  if (!task) return fail(`${slug} no está en BACKLOG: sólo se prepara trabajo ya promovido.`, USAGE)
 
   // No reserva —eso es `claim`— pero se niega a montar sobre lo de otro: preparar un árbol para una
   // tarea ajena es trabajo que se va a tirar, y el aviso cuesta menos que descubrirlo después.
   const taken = state.claims.find((one) => one.slug === slug)
   if (taken && taken.runner !== CL.runner()) {
-    return fail(`${slug} la tomó ${taken.owner}; preparar un árbol para su tarea no ayuda a nadie.`)
+    return fail(`${slug} la tomó ${taken.owner}; preparar un árbol para su tarea no ayuda a nadie.`, REFUSED)
   }
 
   const candidatos = R.reposFor(path.join(root, '..'), task.service)
   if (candidatos.length > 1) {
     return fail(`${task.service || '.'} existe en más de un repositorio (${candidatos.join(', ')}), así que `
-      + 'no puedo saber cuál. Escribí un `service:` que sólo exista en uno.', 2)
+      + 'no puedo saber cuál. Escribí un `service:` que sólo exista en uno.', USAGE)
   }
   const repo = candidatos[0]
   if (!repo) {
     return fail(`no encontré el repositorio de ${task.service || '(sin service)'}: revisá workspaceRoots `
-      + 'en ops.config.json y que la ruta del servicio exista.', 2)
+      + 'en ops.config.json y que la ruta del servicio exista.', USAGE)
   }
 
   const branch = CL.branchOf(slug)
   const already = existing(repo, branch)
   const target = already || path.join(path.dirname(repo), `${path.basename(repo)}-${slug}`)
   if (!already) {
-    if (fs.existsSync(target)) return fail(`${target} ya existe y no es un árbol de esta rama.`)
+    if (fs.existsSync(target)) return fail(`${target} ya existe y no es un árbol de esta rama.`, REFUSED)
     const hasBranch = git(repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`).status === 0
     const args = hasBranch ? ['worktree', 'add', target, branch] : ['worktree', 'add', '-b', branch, target]
     const added = git(repo, ...args)
-    if (added.status !== 0) return fail(`git worktree add falló: ${(added.stderr || '').trim()}`)
+    if (added.status !== 0) return fail(`git worktree add falló: ${(added.stderr || '').trim()}`, REFUSED)
   }
 
   if (cli.has('--json')) {

package/engine/core/ownership.js

@@ -164,9 +164,16 @@ function engineAt(root, relative = '') {
 // de copiarse. Se reconocen por contener `system/`, que es el espacio del toolkit y no algo que un
 // proyecto deba crear. Una sola implementación para las dos, o divergen.
 function packageDir(root, name) {
+  // La raíz declarada va también acá, y no sólo en `packagePath`. Las dos contestan dónde está el paquete
+  // sobre la misma instancia y desde el 158 contestaban distinto: en el layout documentado —`npm install`
+  // en la carpeta de la empresa y la instancia adentro— el motor se resolvía y el catálogo no, así que
+  // `check` pasaba en verde y `agents list` devolvía una lista vacía con exit 0, indistinguible de «esta
+  // instancia no tiene cargos». `evaluate` era peor: culpaba a un `SKILL.md` que falta (caso 171).
+  const above = declaredRoot(root)
   const candidates = [
     path.join(root, 'node_modules', '@ingeniomaps', 'cauce', name),
     path.join(root, name),
+    ...(above ? [path.join(above, 'node_modules', '@ingeniomaps', 'cauce', name)] : []),
   ]
   return candidates.find((dir) => fs.existsSync(path.join(dir, 'system'))
     || fs.existsSync(path.join(dir, 'roles', 'system'))) || ''

package/package.json

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