@ingeniomaps/cauce 0.93.0 → 0.95.0

package/engine/automation/index.js

@@ -45,9 +45,9 @@ function probeBridge(paths, runner) {
   const problems = []
   // Desde la raíz y desde una carpeta de adentro: si el runner lanza el hook con otro cwd, la ruta
   // relativa de su configuración deja de resolver y eso hay que verlo acá, no en la primera sesión.
-  const sourceRoot = [paths.install, path.dirname(script)]
+  const launchDirs = [paths.install, path.dirname(script)]
   for (const event of hookEvents) {
-    for (const cwd of sourceRoot) {
+    for (const cwd of launchDirs) {
       const payload = JSON.stringify({ toolCall: { args: { CommandLine: 'ls', Cwd: paths.install } } })
       const result = spawnSync(process.execPath, [script, event], { cwd, input: payload, encoding: 'utf8' })
       let response = {}
@@ -75,11 +75,11 @@ function doctor(root, name, output = console) {
   const warnings = []
   try {
     const expected = runnerConfig(paths, root)
-    const actual = JSON.parse(fs.readFileSync(paths.configTarget, 'utf8'))
-    if (!includesConfig(actual, expected)) {
+    const installed = JSON.parse(fs.readFileSync(paths.configTarget, 'utf8'))
+    if (!includesConfig(installed, expected)) {
       errors.push(`${runner.config.target}: configuración instalada incompleta o divergente`)
     }
-    const legacy = legacyGuardWiring(actual)
+    const legacy = legacyGuardWiring(installed)
     if (legacy.length) {
       warnings.push(`${runner.config.target}: ${legacy.join(', ')} siguen registrados sueltos junto al grupo; `
         + 'cada uno se ejecuta dos veces. Borrá esas entradas del archivo para quedarte sólo con el grupo')
@@ -221,6 +221,18 @@ function uninstall(root, name, output = console) {
   }
   const runner = runnerManifest(root, name)
   const paths = runnerPaths(root, name, runner)
+  // La configuración se lee **antes** de borrar nada, aunque se use al final. Leyéndola al final, un
+  // `settings.json` a medio fusionar hacía morir el comando con el mensaje crudo del parser —que no
+  // nombra ni un archivo— con los workflows y los cargos ya borrados: la instancia quedaba a medio
+  // desinstalar, con la configuración registrando guards que no existen. Acá no hay nada que deshacer
+  // porque todavía no se tocó el disco, que es más barato que cualquier rollback.
+  const hasConfig = fs.existsSync(paths.configTarget)
+  let config
+  if (hasConfig) {
+    try { config = JSON.parse(fs.readFileSync(paths.configTarget, 'utf8')) } catch (error) {
+      throw new Error(`${runner.config.target} contiene JSON inválido (${error.message})`)
+    }
+  }
   const prefix = opsPrefix(root)
   const recorded = M.readRunners(root)
   const kept = []
@@ -266,9 +278,8 @@ function uninstall(root, name, output = console) {
     }
   }
 
-  if (fs.existsSync(paths.configTarget)) {
-    const current = JSON.parse(fs.readFileSync(paths.configTarget, 'utf8'))
-    const clean = unmergeConfig(unmergeConfig(current, runnerConfig(paths, root)), runner.config.retired || {})
+  if (hasConfig) {
+    const clean = unmergeConfig(unmergeConfig(config, runnerConfig(paths, root)), runner.config.retired || {})
     if (clean && Object.keys(clean).length) F.atomicWriteJson(paths.configTarget, clean)
     else { removeFile(paths.configTarget, paths.install); removed += 1 }
     output.log(`✓ ${name}: ${runner.config.target} sin las entradas de Cauce`)

package/engine/automation/rules.js

@@ -67,38 +67,56 @@ function split(root) {
 function weight(root) {
   const { loaded } = split(root)
   let bytes = 0
+  let own = 0
   const files = []
   for (const file of loaded) {
     try {
       const size = fs.statSync(path.join(root, file)).size
       bytes += size
+      // Lo propio es lo que no vive en `rules/system/`, que es exactamente lo que el proyecto escribió:
+      // una regla del sistema que sobrescribió deja de cargarse y la suya ocupa su lugar, así que
+      // contarla como propia es correcto — la escribió él y la puede achicar.
+      if (!file.includes('/system/')) own += size
       files.push({ file, size })
     } catch { /* la que no está en disco ya la reporta `check` por su lado */ }
   }
-  return { count: loaded.length, bytes, files: files.sort((a, b) => b.size - a.size) }
+  return { count: loaded.length, bytes, own, files: files.sort((a, b) => b.size - a.size) }
 }
 
 const KB = (bytes) => `${(bytes / 1024).toFixed(1)} KB`
 
-// A partir de dónde el peso deja de ser el costo de arrancar y pasa a ser una decisión que conviene mirar.
-// El piso que Cauce impone —las cuatro reglas del sistema— son 38,3 KB, así que un umbral por debajo de
-// eso avisaría en toda instancia recién creada y se apagaría por ruido el primer día: eso descartó los
-// 60 KB que el caso 141 proponía. 64 KB deja ~26 KB para lo propio, que son varias reglas de tamaño
-// normal, antes de que el aviso hable.
+// A partir de dónde lo que el proyecto agregó deja de ser el costo de arrancar y pasa a ser una decisión
+// que conviene mirar. **Se compara contra lo propio y no contra el total**, y esa es la diferencia que
+// hace al número significar algo.
+//
+// Contra el total, el piso del toolkit y las reglas de la empresa salían del mismo bolsillo: el aviso
+// decía «tu bloque pesa» cuando la mitad la habíamos puesto nosotros, y cada regla que Cauce agregaba le
+// achicaba el margen sin que nadie lo decidiera. El 64 tampoco salió de un costo medido: salió de
+// esquivar nuestro propio piso —el caso 141 proponía 60 y se subió porque lo que Cauce ponía ya eran
+// 61,9 KB—, así que había que reelegirlo cada vez que el toolkit enseñaba algo. Medido sobre lo propio,
+// el número deja de depender de nosotros y no se toca cuando el piso crece.
+//
+// El valor sigue siendo el que había, y eso es a propósito: cambiar qué se mide y cuánto a la vez deja
+// sin saber cuál de los dos movió el resultado. Lo que se sabe hoy es que **64 está por debajo de lo que
+// una empresa real usa**: una instancia medida tiene 93,8 KB de reglas propias, así que el aviso le sale
+// desde el día que instaló. Elegir el número con esa evidencia es una decisión aparte, y la cuenta que la
+// habilita está en el 141: 61,9 KB ≈ 15,9 K tokens, o sea ~3,9 KB por 1K tokens en **cada** agente.
 const HEAVY = 64 * 1024
 
 // La línea que declara el peso, para que la digan igual `install` y `check`. Nombra las dos más grandes
 // porque es lo accionable: saber que el bloque pesa no dice cuál conviene declarar por superficie.
 function weightLine(root) {
-  const { count, bytes, files } = weight(root)
+  const { count, bytes, own, files } = weight(root)
   const top = files.slice(0, 2).map((one) => path.basename(one.file)).join(', ')
+  // El total es lo que paga el agente y lo propio es lo único sobre lo que el proyecto puede hacer algo,
+  // así que van los dos: con uno solo, o el número no es el costo real o no es accionable.
   return `el bloque de reglas carga ${count} archivo(s), ${KB(bytes)} en cada agente`
-    + (top ? ` (las más grandes: ${top})` : '')
+    + ` (${KB(own)} propias)${top ? ` (las más grandes: ${top})` : ''}`
 }
 
 // Sólo cuando pasó el umbral. Devuelve lista porque es lo que `check` empalma con el resto de avisos.
 function heavyRules(root) {
-  return weight(root).bytes > HEAVY ? [weightLine(root)] : []
+  return weight(root).own > HEAVY ? [weightLine(root)] : []
 }
 
 // Sin raíz el marcador queda como está —así lo leen las pruebas que revisan el texto de un adaptador—: un

package/engine/cli/archive.js

@@ -11,10 +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 } = require('./io')
-
-// La fecha de hoy, la misma que usan los comandos que leen.
-const TODAY = () => new Date().toISOString().slice(0, 10)
+const { fail, planningRoot, TODAY } = 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

package/engine/cli/args.js

@@ -41,6 +41,12 @@ const FLAGS = {
   flow: ['--json'],
 }
 
+// Qué banderas acepta un comando, y `[]` si el comando no existe. `FLAGS[nombre]` a secas resuelve
+// contra `Object.prototype`, así que `constructor` contestaba una función —que es verdadera, y el CLI
+// daba el comando por bueno— y `toString` contestaba un método sin `.includes`, que reventaba acá
+// mismo. No es un nombre exótico: es lo que sale de pasarle a `ops` una variable que vino vacía.
+const accepted = (command) => (Object.hasOwn(FLAGS, command) ? FLAGS[command] : [])
+
 // La línea de comandos, leída una sola vez. Antes cada función buscaba sus banderas en
 // `process.argv`, veinticinco veces y a cualquier profundidad: `evaluationBench` sacaba `--force` de
 // ahí en vez de recibirlo, así que su firma no decía de qué dependía y probar un comando exigía
@@ -51,6 +57,10 @@ function parse(argv) {
   const positional = []
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index]
+    // `-h` es la única bandera corta que el CLI anuncia, y como no empieza con `--` caía de posicional:
+    // `ops check -h` tomaba `-h` por la raíz del planning y contestaba que ahí no había ninguno. Se
+    // normaliza a `--help` para que adentro haya una sola grafía y nadie tenga que preguntar por las dos.
+    if (value === '-h') { flags.add('--help'); continue }
     if (!value.startsWith('--')) { positional.push(value); continue }
     flags.add(value)
     if (VALUED_FLAGS.has(value)) { values[value] = argv[index + 1] || ''; index += 1 }
@@ -60,8 +70,12 @@ function parse(argv) {
     has: (flag) => flags.has(flag),
     value: (flag, fallback = '') => values[flag] || fallback,
     // Lo que el comando no declara en `FLAGS`. Se calcula sobre `flags` y no sobre argv crudo para
-    // que el valor de una bandera con valor no se confunda con una bandera suelta.
-    unknown: (command) => [...flags].filter((flag) => !FLAGS[command].includes(flag)),
+    // que el valor de una bandera con valor no se confunda con una bandera suelta. `--help` la acepta
+    // cualquier comando y por eso no la declara ninguno: sin esta excepción, pedir ayuda sería una
+    // bandera desconocida.
+    unknown: (command) => [...flags]
+      .filter((flag) => flag !== '--help')
+      .filter((flag) => !accepted(command).includes(flag)),
   }
 }
 

package/engine/cli/bench.js

@@ -73,9 +73,9 @@ function benchSurvived(dir, since) {
 // la rama se ejerce en milisegundos y sobre un temporal que la prueba acaba de crear.
 function clearBench(dir, scratch, remove = fs.rmSync) {
   const target = path.resolve(dir)
-  const banco = path.resolve(scratch)
-  if (!target.startsWith(banco + path.sep)) {
-    return `no se borra ${target}: no cuelga de ${banco}, así que no es un banco de evaluación.`
+  const benchRoot = path.resolve(scratch)
+  if (!target.startsWith(benchRoot + path.sep)) {
+    return `no se borra ${target}: no cuelga de ${benchRoot}, así que no es un banco de evaluación.`
   }
   // El instante de arranque, para poder fechar lo que sobreviva: es lo único que separa un archivo que el
   // borrado no tocó de uno que alguien reescribió mientras borrábamos.

package/engine/cli/catalog.js

@@ -13,13 +13,13 @@ 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 } = require('./io')
+const { fail, opsRoot, TODAY } = require('./io')
 
 function agentsFork(slug, dir) {
   const root = opsRoot(dir)
   if (!slug) fail('Falta el cargo: ops agents fork <cargo> [ops-root]', 2)
   let result
-  const date = new Date().toISOString().slice(0, 10)
+  const date = TODAY()
   try { result = require('../agents/fork').fork(root, slug, date) } catch (error) { fail(error.message, 2) }
   console.log(`+ ${path.relative(root, result.dir)} (${result.files.length} archivo(s))`)
   if (result.skipped.length) {
@@ -179,7 +179,7 @@ function evaluate(agent, caso, cli) {
     // Dónde escribir el registro de esta corrida. Lo pregunta el recorrido en vez de componer el
     // nombre, que es lo que hacía que la segunda corrida de un día borrara a la primera.
     if (cli.has('--record')) {
-      const day = cli.value('--record') || new Date().toISOString().slice(0, 10)
+      const day = cli.value('--record') || TODAY()
       return console.log(path.relative(root,
         path.join(EV.resultsDir(root, agent, kind), EV.nextResult(root, agent, day, kind))))
     }

package/engine/cli/claims.js

@@ -9,9 +9,7 @@ const path = require('node:path')
 const CL = require('../planning/claims')
 const R = require('../core/repos')
 const ST = require('../planning/state')
-const { fail, planningRoot } = require('./io')
-
-const TODAY = () => new Date().toISOString().slice(0, 10)
+const { fail, planningRoot, TODAY } = require('./io')
 
 function claim(dir, slug, cli) {
   const root = planningRoot(dir)
@@ -22,8 +20,8 @@ function claim(dir, slug, cli) {
 
   // 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 falta = task.depends.find((dep) => !state.done.set.has(dep))
-  if (falta) return fail(`${slug} depende de ${falta}, que todavía no está en DONE.`)
+  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.`)
 
   const me = CL.owner(root)
   const from = CL.runner()
@@ -45,7 +43,7 @@ function claim(dir, slug, cli) {
 
   const target = CL.file(root, slug)
   fs.mkdirSync(path.dirname(target), { recursive: true })
-  const cuerpo = CL.content({ task: slug, owner: me, runner: from, started: TODAY(), service: task.service })
+  const body = CL.content({ task: slug, owner: me, runner: from, started: TODAY(), service: task.service })
   try {
     // Reservar **es** crear el archivo, así que el único juez de quién la tiene es el archivo. `wx` falla
     // si ya está, y de ahí sale la respuesta entera: propia, ajena o perdida en la carrera.
@@ -54,25 +52,25 @@ function claim(dir, slug, cli) {
     // de diferencia ganarían los dos sin que ninguno se entere. Y una comprobación previa tampoco
     // alcanzaría —entre mirar y escribir queda la misma ventana—, así que sería un segundo juez que
     // adelanta un veredicto que este bloque tiene que volver a dar igual.
-    fs.writeFileSync(target, cuerpo, { flag: 'wx' })
+    fs.writeFileSync(target, body, { flag: 'wx' })
   } catch (error) {
     if (error.code !== 'EEXIST') throw error
-    const dueño = CL.read(root).find((one) => one.slug === slug)
+    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 (!dueño) return fail(`${slug} cambió de manos mientras la pedías; volvé a intentarlo.`)
-    if (dueño.runner === from) return console.log(`= ${slug} ya era tuya desde ${dueño.started}`)
+    if (!holder) return fail(`${slug} cambió de manos mientras la pedías; volvé a intentarlo.`)
+    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.
     // Retomarla sola le sacaría la tarea al otro agente; crear un runner nuevo dejaría dos trabajando lo
     // mismo. Las dos rompen trabajo, así que decide una persona y acá sólo se dice cuál es cuál.
-    if (dueño.owner === me) {
-      return fail(`${slug} la tenés vos, tomada el ${dueño.started} desde el runner ${dueño.runner}. `
+    if (holder.owner === me) {
+      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.')
     }
-    return fail(`${slug} la tomó ${dueño.owner} el ${dueño.started}. Si se abandonó, borrá `
+    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.`)
   }
   console.log(`✓ ${slug} tomada por ${me}`)
@@ -111,20 +109,20 @@ function release(dir, slug) {
 function runners(dir, cli) {
   const root = planningRoot(dir)
   const done = ST.snapshot(root).done
-  const abiertos = CL.read(root).filter((one) => !done.set.has(one.slug))
-  const hoy = TODAY()
-  const filas = abiertos.map((one) => {
+  const open = CL.read(root).filter((one) => !done.set.has(one.slug))
+  const today = TODAY()
+  const rows = open.map((one) => {
     const commit = R.lastCommit(R.repoOf(path.join(root, '..'), one.service), CL.branchOf(one.slug))
     return { runner: one.runner, task: one.slug, owner: one.owner, started: one.started, lastCommit: commit }
   })
-  if (cli.has('--json')) return console.log(JSON.stringify(filas))
-  if (!filas.length) return console.log('= ningún runner tiene trabajo abierto: arrancá con un id propio')
-  const ancho = Math.max(...filas.map((one) => one.runner.length))
-  for (const una of filas) {
-    const avance = una.lastCommit ? `último commit ${una.lastCommit}` : 'sin commits en su rama'
-    console.log(`${una.runner.padEnd(ancho)}  ${una.task}  (${una.owner}, desde ${una.started}; ${avance})`)
+  if (cli.has('--json')) return console.log(JSON.stringify(rows))
+  if (!rows.length) return console.log('= ningún runner tiene trabajo abierto: arrancá con un id propio')
+  const width = Math.max(...rows.map((one) => one.runner.length))
+  for (const row of rows) {
+    const progress = row.lastCommit ? `último commit ${row.lastCommit}` : 'sin commits en su rama'
+    console.log(`${row.runner.padEnd(width)}  ${row.task}  (${row.owner}, desde ${row.started}; ${progress})`)
   }
-  console.log(`\n${filas.length} runner(s) con trabajo abierto al ${hoy}. `
+  console.log(`\n${rows.length} runner(s) con trabajo abierto al ${today}. `
     + 'Retomá uno usando su id, o arrancá con uno propio.')
 }
 

package/engine/cli/contract.js

@@ -83,9 +83,18 @@ const MARKED = /^###\s+Límites\s*$/m
 // llevaba adentro los cuatro párrafos que la persona había agregado al final de la sección. Descontar el
 // bloque entero —que es lo que parecía el arreglo— apagaba justo lo que el aviso existe para encontrar.
 const BULLET = /^\s*[-*]\s+/
+// Una viñeta es la viñeta entera, no su primera línea. Un límite de verdad no entra en el ancho del
+// archivo, así que se escribe en dos, y recorriendo línea por línea lo que viajaba al preámbulo de cada
+// subagente era la mitad — cortada justo donde suele estar lo que el límite decide (caso 168).
+//
+// `own` son las líneas **sin plegar**, y existe para `warnings`: descuenta por línea contra lo que el
+// archivo tiene escrito (caso 159), y una viñeta ya plegada no coincide con ninguna de esas líneas, así
+// que su continuación volvía a contarse como un párrafo perdido. Son dos preguntas distintas sobre el
+// mismo bloque: qué dice cada límite, y qué líneas ya están cubiertas.
 function marked(raw) {
   const bullets = []
   const intros = []
+  const own = []
   let rest = raw
   for (let start = rest.search(MARKED); start >= 0; start = rest.search(MARKED)) {
     const after = rest.slice(start).split('\n').slice(1)
@@ -93,13 +102,21 @@ function marked(raw) {
     const block = end < 0 ? after : after.slice(0, end)
     const first = block.findIndex((line) => BULLET.test(line))
     if (first > 0) intros.push(...block.slice(0, first).map((line) => line.trim()).filter(Boolean))
-    bullets.push(...block
-      .filter((line) => BULLET.test(line))
-      .map((line) => line.replace(BULLET, '').trim())
-      .filter(Boolean))
+    // Una línea en blanco cierra la viñeta abierta: lo que venga después es otra cosa y pegarlo ahí
+    // uniría dos límites en uno.
+    let open = -1
+    for (const line of first < 0 ? [] : block.slice(first)) {
+      const text = line.replace(BULLET, '').trim()
+      if (!text) { open = -1; continue }
+      // A `own` va lo que pertenece a una viñeta y nada más. Empujar toda línea no vacía haría que la
+      // prosa suelta que quedó bajo el encabezado contara como declarada y `warnings` dejara de nombrarla:
+      // el plegado apagaría el aviso en vez de arreglar el límite.
+      if (BULLET.test(line)) { bullets.push(text); open = bullets.length - 1; own.push(text) }
+      else if (open >= 0) { bullets[open] += ` ${text}`; own.push(text) }
+    }
     rest = (end < 0 ? '' : after.slice(end).join('\n'))
   }
-  return { bullets, intros }
+  return { bullets, intros, own }
 }
 
 const declared = (raw) => marked(raw).bullets
@@ -147,8 +164,8 @@ function warnings(root) {
   // Se descuenta por línea y no por párrafo, que es donde estaba el defecto: `paragraphs` saca el `- ` y
   // une las viñetas seguidas en un párrafo solo, así que una lista declarada no era igual a ninguna
   // entrada de `declared()` y se contaba entera como un límite perdido (caso 159).
-  const { bullets, intros } = marked(mine)
-  const suyo = new Set([...bullets, ...intros])
+  const { own, intros } = marked(mine)
+  const suyo = new Set([...own, ...intros])
   const outside = P.withoutComments(mine).split('\n')
     .filter((line) => !suyo.has(line.replace(BULLET, '').trim()))
     .join('\n')

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 } = require('./io')
 const { declareEngine, pinEngine, undeclareEngine } = require('./dependency')
 const { adviceFor, previewUpgrade, reportUpgrade } = require('./upgrade-report')
 
@@ -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
@@ -309,17 +309,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 +345,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 +368,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 +389,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 +398,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 +413,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 +428,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 +447,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/ops.js

@@ -195,11 +195,15 @@ 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}`, 2) }
   // `--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.'

package/engine/cli/planning.js

@@ -141,7 +141,7 @@ 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)
@@ -150,7 +150,7 @@ function context(dir, cli) {
       const hay = state.milestones.map((one) => one.slug).join(', ') || '(ninguno)'
       return fail(`el hito ${hito} no existe. Hay: ${hay}`, 2)
     }
-    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}\``)

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

@@ -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, '..'))