@ingeniomaps/cauce 0.94.0 → 0.96.0

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 } = 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)
@@ -98,7 +98,7 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-    ...RC.sinceValues(new Date().toISOString().slice(0, 10)),
+    ...RC.sinceValues(TODAY()),
   }, force, providerNames(), quiet)
   // No se copia `.github/`: `ci.yml` valida el toolkit con `npm run ci` —que una instancia no tiene— y
   // el ciclo de aprendizaje dejó de distribuirse en 0.4.0. Copiar salteando lo que no aplica dejaba
@@ -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,
     )
   }
 
@@ -309,17 +310,17 @@ function upgrade(dir, cli) {
   //
   // El aviso sale en **cada** corrida y no sólo la primera: una instancia con medio molde congelado y
   // sin enterarse es el otro modo de fallo, y es silencioso.
-  const conservados = force ? new Set() : new Set(changed)
-  if (conservados.size) {
-    for (const file of conservados) console.log(`= conservado ${file} (editado localmente)`)
-    console.log(`\n${conservados.size} archivo(s) del molde quedan congelados por tu edición.`)
-    console.log(`${adviceFor([...conservados])}\n`)
+  const keptFiles = force ? new Set() : new Set(changed)
+  if (keptFiles.size) {
+    for (const file of keptFiles) console.log(`= conservado ${file} (editado localmente)`)
+    console.log(`\n${keptFiles.size} archivo(s) del molde quedan congelados por tu edición.`)
+    console.log(`${adviceFor([...keptFiles])}\n`)
     console.log('Para tomar la versión nueva y descartar la tuya, repetí con --force.\n')
   }
   // Un archivo propio que se llama como uno que el paquete empieza a traer (caso 110): se conserva y se
   // dice, igual que una edición local, y `--force` lo reemplaza diciéndolo.
-  const choques = new Set(force ? [] : colliding)
-  for (const file of choques) {
+  const collisions = new Set(force ? [] : colliding)
+  for (const file of collisions) {
     console.log(`= conservado ${file}: ya existía y Cauce no lo entregó, así que el del paquete no se `
       + 'instaló. Renombrá el tuyo y repetí, o repetí con --force para reemplazarlo.')
   }
@@ -345,7 +346,7 @@ function upgrade(dir, cli) {
       '{{PROJECT_NAME}}': config.project || path.basename(root),
       '{{MODE}}': O.mode(root),
       '{{WORKSPACE_PATH}}': O.mode(root) === 'embedded' ? '.' : '..',
-      ...RC.sinceValues(new Date().toISOString().slice(0, 10)),
+      ...RC.sinceValues(TODAY()),
     })) content = content.replaceAll(key, value)
     F.atomicWrite(target, content)
     added.push(relative)
@@ -368,13 +369,13 @@ function upgrade(dir, cli) {
 
   const conservar = (file) => {
     const relative = path.relative(root, file).replace(/\\/g, '/')
-    return conservados.has(relative) || choques.has(relative)
+    return keptFiles.has(relative) || collisions.has(relative)
   }
   for (const relative of [...system, ...O.RUNTIME_PATHS]) {
     const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
     if (!fs.existsSync(origin)) continue
     const target = path.join(root, relative)
-    if (conservados.has(relative)) continue
+    if (keptFiles.has(relative)) continue
     // Sobrescribe lo que trae el paquete y deja intacto lo demás: un guard propio de la empresa,
     // o un adaptador de runner que el toolkit no conoce, sobreviven a la actualización.
     if (fs.statSync(origin).isDirectory()) copyRuntime(origin, target, false, root, [], conservar)
@@ -389,7 +390,7 @@ function upgrade(dir, cli) {
 
   // Retirar lo que el toolkit ya no distribuye, después de haber actualizado lo que sí.
   const retired = []
-  const pendientes = []
+  const pending = []
   for (const relative of O.RETIRED) {
     const target = path.join(root, relative)
     if (!fs.existsSync(target)) continue
@@ -398,10 +399,10 @@ function upgrade(dir, cli) {
     // también usa para lo suyo, borrar el directorio entero se llevaba puesto contenido que nadie
     // había entregado —un `autobuild.js` propio, los workflows de una empresa— sin confirmación y sin
     // vuelta atrás. Se conserva y se nombra; `--force` es la salida, igual que para una edición local.
-    const contenido = O.RETIRED_COMPARTIDO.includes(relative) && fs.statSync(target).isDirectory()
+    const leftover = O.RETIRED_SHARED.includes(relative) && fs.statSync(target).isDirectory()
       ? O.treeFiles(target)
       : []
-    if (contenido.length && !force) { pendientes.push({ relative, files: contenido }); continue }
+    if (leftover.length && !force) { pending.push({ relative, files: leftover }); continue }
     fs.rmSync(target, { recursive: true, force: true })
     retired.push(relative)
   }
@@ -413,7 +414,7 @@ function upgrade(dir, cli) {
   // conservar **ese** digest: registrar el de disco lo volvería idéntico a lo entregado, dejaría de
   // detectarse como editado y la corrida siguiente lo pisaría sin decir nada. Es el 001 de vuelta por
   // la puerta de atrás, y no se ve mirando el archivo — se ve dos upgrades después.
-  const entregado = { ...record }
+  const delivered = { ...record }
   for (const relative of O.trackedPaths()) {
     if (fs.existsSync(path.join(root, relative))) {
       record = M.record(root, relative, O.deliveredFiles(root, relative), record)
@@ -428,8 +429,8 @@ function upgrade(dir, cli) {
     }
   }
   record = M.recordPaths(root, O.SYSTEM_FILES, record)
-  for (const file of conservados) if (entregado[file]) record[file] = entregado[file]
-  for (const file of choques) delete record[file]
+  for (const file of keptFiles) if (delivered[file]) record[file] = delivered[file]
+  for (const file of collisions) delete record[file]
   // El registro de forks se poda igual que el de archivos: un cargo devuelto al catálogo deja su
   // entrada, y una entrada sin copia sólo puede producir avisos sobre algo que no está.
   const kept = Object.fromEntries(Object.entries(M.readForks(root)).filter(
@@ -447,7 +448,7 @@ function upgrade(dir, cli) {
   // que no ocurrieron (caso 048).
   reportUpgrade({
     root, from, to, system, retired, added, overrides, pinned, droppedBlocks,
-    descartados: force ? changed : [], conservados: [...conservados], pendientes,
+    discarded: force ? changed : [], keptFiles: [...keptFiles], pending,
   })
 }
 

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
@@ -195,15 +200,19 @@ const NO_FLAGS = { has: () => false, value: (_flag, fallback = '') => fallback }
 
 async function run(cli) {
   const [command] = cli.positional
-  if (!command || ['help', '--help', '-h'].includes(command)) return usage()
-  if (!FLAGS[command]) { usage(); fail(`Comando desconocido: ${command}`, 2) }
+  // `--help` y `-h` nunca llegan acá: `parse` los reconoce como banderas, así que el posicional queda
+  // vacío y lo atiende el `!command` de al lado. Lo que sí es un posicional es `help` a secas.
+  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}`, 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') || cli.has('-h')) return usage()
+  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)
@@ -232,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 */ }
@@ -141,16 +141,16 @@ function context(dir, cli) {
   // Un filtro elige dónde buscar trabajo **nuevo**; no puede esconder el que ya tenés. Sin esto, pedir
   // otro hito mientras sostenías una tarea ofrecía una segunda que `claim` después se niega a dar: el
   // comando que dice qué hacer y el que lo autoriza contestaban distinto, y sólo se veía al reclamar.
-  const propio = state.claims.find((one) => one.runner === from && !state.done.set.has(one.slug))
+  const own = state.claims.find((one) => one.runner === from && !state.done.set.has(one.slug))
   let hitoOmitido = ''
   if (hito) {
     const existe = state.milestones.some((one) => one.slug === hito)
     // 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 (propio) hitoOmitido = `${hito} no se aplica: ya tenés ${propio.slug} tomada`
+    if (own) hitoOmitido = `${hito} no se aplica: ya tenés ${own.slug} tomada`
     else state.milestones = state.milestones.filter((one) => one.slug === hito)
   }
   const gate = path.join(root, 'AWAITING_REVIEW.md')
@@ -222,13 +222,13 @@ function context(dir, cli) {
   // Es el comando que existe para decir qué toca ahora, contestando «nada» cuando lo que toca es eso.
   // Tu propio nombre en una tarea «ajena» es la señal de que sos vos desde otro runner, y sin decirlo se
   // lee como que alguien te ganó la tarea.
-  const dueño = (one) => (one.owner === report.owner ? `${one.owner} — vos, desde otro runner` : one.owner)
+  const ownerLabel = (one) => (one.owner === report.owner ? `${one.owner} — vos, desde otro runner` : one.owner)
   // Que el reclamo sea tuyo desde otro id ya se decía; que además haya un **plan escrito** bajo ese id, no.
   // Esa es la mitad que cuesta la sesión: los pasos ya hechos están en un archivo que nadie nombra, y el id
   // que lo recupera es justo el que esta sesión no supo deducir. Los dos datos están en el reclamo.
   const tomadas = () => {
     for (const one of report.taken) {
-      console.log(`TAKEN  ${one.slug} (${dueño(one)})`)
+      console.log(`TAKEN  ${one.slug} (${ownerLabel(one)})`)
       if (one.owner === report.owner && one.wip) {
         console.log(`PLAN   ${one.slug}: su plan está en wip/${one.wip} — retomalo con `
           + `\`export CAUCE_RUNNER=${one.runner}\``)
@@ -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/upgrade-report.js

@@ -26,7 +26,7 @@ function adviceFor(changed) {
   const advice = []
   if (ruleFiles.length) {
     advice.push(
-      'Las ruleFiles y decisiones bajo system/ son del toolkit. Para cambiar una, escribí la tuya al\n'
+      'Las reglas y decisiones bajo system/ son del toolkit. Para cambiar una, escribí la tuya al\n'
       + 'lado con el mismo ID: el proyecto manda y `check` lo reporta como override explícito.',
     )
   }
@@ -47,11 +47,11 @@ function adviceFor(changed) {
   // El consejo de arriba manda mudar lo propio a donde sí es del proyecto, y para estos cuatro no hay
   // adónde: no existe un PROTOCOL de la empresa que le gane al del toolkit como sí lo hay en `rules/`.
   // Sin decirlo, quien adoptó Cauce sobre su propio proceso lee un consejo que no puede seguir.
-  const SIN_CONTRAPARTE = ['planning/PROTOCOL.md', 'planning/METHODOLOGY.md', 'planning/FLOW.md', 'Makefile']
-  const propios = docs.filter((file) => SIN_CONTRAPARTE.includes(file))
-  if (propios.length) {
+  const NO_COUNTERPART = ['planning/PROTOCOL.md', 'planning/METHODOLOGY.md', 'planning/FLOW.md', 'Makefile']
+  const ownDocs = docs.filter((file) => NO_COUNTERPART.includes(file))
+  if (ownDocs.length) {
     advice.push(
-      `${propios.join(', ')} no tienen contraparte propia adónde mudarse: son del toolkit y no hay\n`
+      `${ownDocs.join(', ')} no tienen contraparte propia adónde mudarse: son del toolkit y no hay\n`
       + 'una versión del proyecto que le gane. Quedan congelados con tu versión y el resto se actualiza\n'
       + 'igual. Adoptar el del toolkit es trabajo propio —comparar los dos procesos y decidir—, no un flag.',
     )
@@ -74,18 +74,18 @@ function adviceFor(changed) {
 // entero en vez de recalcular nada: lo que se informa es exactamente lo que ocurrió.
 function reportUpgrade({
   root, from, to, system, retired, added, overrides, pinned, droppedBlocks,
-  descartados, conservados, pendientes,
+  discarded, keptFiles, pending,
 }) {
   console.log(`✓ Cauce ${from || '(previa)'} → ${to}`)
   // Descartar con --force es legítimo; hacerlo sin dejar rastro no. Queda en la salida del comando,
   // que es la evidencia que el protocolo pide para cualquier cambio. Y lo que se conservó no se vuelve
   // a enumerar acá: ya salió con su consejo antes de escribir nada, y repetirlo con el glifo del
   // descarte es lo que volvía ilegible el bloque.
-  for (const file of descartados) console.log(`− descartado tu cambio en ${file}`)
-  if (conservados.length) console.log(`= ${conservados.length} archivo(s) conservados por tu edición`)
+  for (const file of discarded) console.log(`− descartado tu cambio en ${file}`)
+  if (keptFiles.length) console.log(`= ${keptFiles.length} archivo(s) conservados por tu edición`)
   for (const relative of retired) console.log(`− retirado ${relative}: Cauce ya no lo distribuye`)
   // Sin glifo de acción porque no hubo ninguna: la ruta sigue ahí y el contenido también.
-  for (const { relative, files } of pendientes) {
+  for (const { relative, files } of pending) {
     console.log(`  ${relative}: ${files.length} archivo(s) que Cauce no entregó; la ruta se retiró y `
       + 'el contenido queda. Movelo adonde lo quieras y borrala, o repetí con --force.')
   }
@@ -103,7 +103,7 @@ function reportUpgrade({
   }
   // Sólo cuando es cierto, y ahora lo decide lo que pasó y no una condición: se dice justo cuando no
   // se descartó nada, que incluye la corrida que conservó veinte archivos.
-  if (!descartados.length) console.log('  planning, organization y todo lo propio quedaron intactos')
+  if (!discarded.length) console.log('  planning, organization y todo lo propio quedaron intactos')
   // No se borra: sin la dependencia declarada, quitarle `.ops/` la dejaría sin motor. Se avisa y
   // decide una persona.
   if (fs.existsSync(path.join(root, '.ops', 'engine'))) {

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)
@@ -137,19 +137,19 @@ function check(dir, cli) {
   // Lo que `upgrade` conserva por estar editado deja de recibir mejoras, y eso es una deuda que no
   // avisa sola: la instancia queda con medio molde viejo y todo se ve normal. Sale acá para que se vea
   // en cada corrida y no sólo el día que alguien actualiza.
-  const congelados = O.localChanges(path.resolve(root, '..'))
-  if (congelados.length) {
-    warnings.push(`${congelados.length} archivo(s) del molde congelados por edición local; `
+  const frozen = O.localChanges(path.resolve(root, '..'))
+  if (frozen.length) {
+    warnings.push(`${frozen.length} archivo(s) del molde congelados por edición local; `
       + '`upgrade` los conserva y no les trae mejoras')
   }
 
   // Y lo que `upgrade` no retiró porque no pudo demostrar que fuera suyo: queda ahí, sin colgar de
   // ningún mecanismo, hasta que alguien lo mueva o lo borre. Se cuenta por lo mismo que los congelados
   // — un resto que no se ve se vuelve permanente.
-  const restos = O.RETIRED_COMPARTIDO.filter((relative) => fs.existsSync(path.join(root, '..', relative)))
-  if (restos.length) {
-    warnings.push(`${restos.length} ruta(s) retiradas siguen en disco con contenido tuyo `
-      + `(${restos.join(', ')}); Cauce ya no las distribuye ni las toca`)
+  const leftovers = O.RETIRED_SHARED.filter((relative) => fs.existsSync(path.join(root, '..', relative)))
+  if (leftovers.length) {
+    warnings.push(`${leftovers.length} ruta(s) retiradas siguen en disco con contenido tuyo `
+      + `(${leftovers.join(', ')}); Cauce ya no las distribuye ni las toca`)
   }
 
   const integration = I.validate(path.resolve(root, '..'))
@@ -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`)
 }