@ingeniomaps/cauce 0.21.0 → 0.23.0

package/engine/agents/fork.js

@@ -6,14 +6,9 @@
 // —que es lo que se ve— y deja atrás los casos adversariales, las fuentes de aprendizaje y el modelo
 // operativo. Queda un cargo que responde igual y ya no se puede evaluar, sin ningún aviso.
 //
-// **Qué no se hereda.** Los informes de aprendizaje, las propuestas y los veredictos de evaluación se
-// quedan en el catálogo. No es prolijidad: un veredicto pertenece al contrato que lo ganó, y el fork
-// nace para dejar de ser ese contrato. Heredarlos le daría a la copia una garantía que no rindió, y
-// una propuesta pendiente arrastraría a la empresa a firmar una decisión que era nuestra.
-//
-// Lo que sí se hereda entero es el contrato y todo lo que lo hace verificable: casos, conductas
-// esperadas, fuentes, automatización y referencias. La empresa recibe un cargo evaluable desde el
-// primer minuto, y a partir de ahí lo mantiene.
+// Se hereda el contrato entero y todo lo que lo hace verificable —casos, conductas esperadas,
+// fuentes, referencias—, así la empresa recibe un cargo evaluable desde el primer minuto. Qué queda
+// afuera y por qué, en `inherited()`.
 
 const fs = require('node:fs')
 const path = require('node:path')
@@ -22,13 +17,9 @@ const catalog = require('./catalog')
 const manifest = require('../core/manifest')
 const ownership = require('../core/ownership')
 
-// Se comparan contra la ruta relativa dentro del cargo. Informes, propuestas y veredictos no viajan:
-// son lo que produjo nuestra versión del contrato, y el fork nace para dejar de ser ese contrato.
-//
-// Antes se exceptuaba `_template.md`, por andamiaje. Ese andamiaje resultó ser muerto —el motor
-// genera el informe y la propuesta desde un molde propio y nunca lee esos archivos— y en un tercio
-// del catálogo contradecía la forma que sí produce, así que se retiró entero. No hay caso especial
-// que preservar.
+// Informes, propuestas y veredictos no viajan: son lo que produjo nuestra versión del contrato, y el
+// fork nace para dejar de ser ese contrato. Heredar un veredicto le daría a la copia una garantía que
+// no rindió; heredar una propuesta pendiente la haría firmar una decisión que era nuestra.
 function inherited(relative) {
   if (/^learning\/(reports|proposals)\//.test(relative)) return false
   if (relative.startsWith('evaluations/results/')) return false
@@ -37,17 +28,8 @@ function inherited(relative) {
 
 const TEXT = /\.(md|ya?ml|json|txt)$/i
 
-function tree(dir, prefix = '') {
-  const found = []
-  let list = []
-  try { list = fs.readdirSync(dir, { withFileTypes: true }) } catch { return found }
-  for (const entry of list) {
-    const relative = prefix ? `${prefix}/${entry.name}` : entry.name
-    if (entry.isDirectory()) found.push(...tree(path.join(dir, entry.name), relative))
-    else found.push(relative)
-  }
-  return found.sort()
-}
+// El mismo recorrido que usa `upgrade`: un cargo es un árbol de archivos como cualquier otro.
+const tree = ownership.treeFiles
 
 // La misma resolución que usa todo lo demás —paquete primero, toolkit después— en vez de deducirla
 // del directorio del motor: la versión que interesa es la del catálogo del que sale la copia.
@@ -74,12 +56,9 @@ function fork(root, slug, date) {
   // En el toolkit no hay a quién copiarle: el catálogo se mantiene acá, directo. Dejarlo pasar creaba
   // un duplicado en `agents/roles/` que tapaba al original, y el trabajo siguiente se hacía sobre la
   // copia mientras la versión que se publica quedaba quieta.
-  try {
-    const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
-    if (config.mode === 'toolkit') {
-      throw new Error(`${slug} vive acá: en el toolkit se edita el catálogo, no se lo copia`)
-    }
-  } catch (error) { if (error instanceof Error && error.message.includes('vive acá')) throw error }
+  if (ownership.mode(root) === 'toolkit') {
+    throw new Error(`${slug} vive acá: en el toolkit se edita el catálogo, no se lo copia`)
+  }
 
   const found = catalog.find(root, slug)
   if (!found.system) {
@@ -89,16 +68,14 @@ function fork(root, slug, date) {
   const target = path.join(root, 'agents', type, slug)
   if (fs.existsSync(target)) throw new Error(`${path.relative(root, target)} ya existe`)
 
-  const files = tree(found.dir).filter(inherited)
+  const todo = tree(found.dir)
+  const files = todo.filter(inherited)
   if (!files.includes('SKILL.md')) throw new Error(`${slug} no tiene SKILL.md: no hay contrato que copiar`)
 
-  // El digest sale del origen, no de la copia. Es lo que el catálogo tenía al momento del fork, y es
-  // contra eso que después se responde «esto mejoró río arriba»; medirlo sobre la copia lo ataría a
-  // cualquier cosa que le hagamos acá —la reescritura de rutas incluida—.
-  //
-  // Y esa reescritura no es cosmética: el `AUTOMATION.md` del catálogo dice «mantené
-  // `agents/<tipo>/system/<slug>`», que en una empresa es el paquete. Copiado tal cual, el aprendizaje
-  // del fork apuntaría a un directorio que el guard bloquea y que npm borra en el próximo install.
+  // El digest sale del origen, no de la copia: es contra lo que el catálogo tenía al forkear que
+  // después se responde «esto mejoró río arriba». Medirlo sobre la copia lo ataría a nuestras propias
+  // ediciones, la reescritura de rutas incluida — y esa reescritura no es cosmética: sin ella el
+  // aprendizaje del fork apuntaría al paquete, que el guard bloquea y npm borra en el próximo install.
   const desde = `agents/${type}/system/${slug}`
   const hacia = `agents/${type}/${slug}`
   const digests = {}
@@ -118,17 +95,16 @@ function fork(root, slug, date) {
   forks[slug] = { type, version, files: digests }
   manifest.write(root, null, null, forks)
 
-  return { slug, type, dir: target, files, version, skipped: tree(found.dir).filter((one) => !inherited(one)) }
+  return { slug, type, dir: target, files, version, skipped: todo.filter((one) => !inherited(one)) }
 }
 
 // Qué cambió en el catálogo desde que la empresa se llevó su copia.
 //
-// El fork es legítimo y esperado —para eso está el comando—, pero deja de recibir las mejoras del
-// toolkit, y eso no puede pasar en silencio: la empresa decidió mantener un cargo, no quedarse sin
-// enterarse de que el original mejoró. Nadie va a comparar 14 archivos a mano en cada actualización.
+// El fork es legítimo, pero deja de recibir las mejoras del toolkit y eso no puede pasar en silencio:
+// la empresa decidió mantener un cargo, no quedarse sin enterarse de que el original mejoró.
 //
 // Se compara contra los digests guardados al forkear, nunca contra la copia: la copia está editada a
-// propósito, así que medir contra ella devolvería «todo cambió» desde el primer ajuste. Y el aviso no
+// propósito, así que medir contra ella devolvería «todo cambió» desde el primer ajuste. El aviso no
 // dice qué hacer —integrar o no es decisión de la empresa—, sólo que hay algo que mirar.
 function drift(root) {
   const forks = manifest.readForks(root)

package/engine/agents/learning.js

@@ -1,9 +1,7 @@
 'use strict'
 
-// Motor de aprendizaje controlado para los perfiles de agentes.
-
-const fs = require('fs')
-const path = require('path')
+const fs = require('node:fs')
+const path = require('node:path')
 const catalog = require('./catalog')
 
 const REQUIRED_SECTIONS = [
@@ -15,10 +13,6 @@ const REQUIRED_SECTIONS = [
   'Aprobación humana',
 ]
 
-function agentRoot(root, agent) {
-  return catalog.resolve(root, agent)
-}
-
 // Un cargo del sistema vive dentro del paquete: escribir ahí perdería el informe en el próximo
 // `npm ci`, y además duplicaría en cada empresa una investigación sobre la profesión que se hace
 // mejor una sola vez. Lo que sí es de esta empresa es su contexto, y ese tiene otro lugar.
@@ -39,6 +33,42 @@ function assertWritable(root, agent) {
 function isoDate(now = new Date()) { return now.toISOString().slice(0, 10) }
 function month(now = new Date()) { return now.toISOString().slice(0, 7) }
 
+const PROPOSAL_NAME = /^\d{4}-\d{2}\.md$/
+
+// El tope de la línea de índice. No es estético: son 47 líneas que se leen de un vistazo, y una que
+// se envuelve rompe la columna que hace posible el vistazo.
+const SUMMARY_MAX = 120
+
+function proposalFiles(dir) {
+  try { return fs.readdirSync(dir).filter((name) => PROPOSAL_NAME.test(name)).sort() } catch { return [] }
+}
+
+function proposalState(text) {
+  return ((text.match(/^status:\s*(\S+)\s*$/m) || [])[1] || 'proposed').toLowerCase()
+}
+
+// El estado terminal del ciclo. Existía la firma, la aplicación y el historial, y faltaba justo el
+// paso que vuelve irrepetible lo ya hecho: `status:` nacía en `proposed` y nadie lo movía nunca.
+//
+// No era un dato desprolijo. `agent-promote` busca la propuesta más nueva y aplica si el estado dice
+// aprobada con responsable — y «aprobada y aplicada» cumple eso—, así que volver a correrlo sobre una
+// propuesta ya aplicada la aplicaba de nuevo. Como los cambios son aditivos por diseño, el resultado
+// no es un error visible sino un contrato con cada viñeta y cada fuente duplicadas.
+function seal(root, agent, period = '') {
+  const dir = path.join(assertWritable(root, agent), 'learning', 'proposals')
+  const names = proposalFiles(dir)
+  if (!names.length) throw new Error(`${agent} no tiene propuestas en learning/proposals/.`)
+  const name = period ? `${period}.md` : names[names.length - 1]
+  if (!names.includes(name)) throw new Error(`${agent} no tiene la propuesta ${name}.`)
+  const file = path.join(dir, name)
+  const text = fs.readFileSync(file, 'utf8')
+  const state = proposalState(text)
+  if (state === 'applied') return { file, already: true }
+  if (!/^status:\s*\S+\s*$/m.test(text)) throw new Error(`${file} no declara status en su frontmatter.`)
+  fs.writeFileSync(file, text.replace(/^status:\s*\S+\s*$/m, 'status: applied'))
+  return { file, already: false }
+}
+
 function prepareReport(root, agent, now = new Date()) {
   const reports = path.join(assertWritable(root, agent), 'learning', 'reports')
   const file = path.join(reports, `${isoDate(now)}.md`)
@@ -136,7 +166,7 @@ Pendiente.
 }
 
 function evaluate(root, agent) {
-  const target = agentRoot(root, agent)
+  const target = catalog.resolve(root, agent)
   const errors = []
   const requiredFiles = [
     'learning/sources.yaml',
@@ -146,7 +176,7 @@ function evaluate(root, agent) {
   // `AUTOMATION.md` documenta cómo corre la automatización de aprendizaje del toolkit. Exigírselo
   // a una empresa que escribe un cargo propio era pedirle contabilidad interna nuestra: su cargo debe
   // tener contrato, fuentes e historia, no nuestro andamiaje.
-  if (require('./catalog').find(root, agent).system) requiredFiles.push('learning/AUTOMATION.md')
+  if (catalog.find(root, agent).system) requiredFiles.push('learning/AUTOMATION.md')
   for (const relative of requiredFiles) {
     if (!fs.existsSync(path.join(target, relative))) errors.push(`falta ${relative}`)
   }
@@ -154,24 +184,32 @@ function evaluate(root, agent) {
   for (const phrase of ['no inventar', 'autorización', 'evidencia observable']) {
     if (!skill.includes(phrase)) errors.push(`SKILL.md no conserva el control: ${phrase}`)
   }
-  let proposals = []
-  try {
-    proposals = fs.readdirSync(path.join(target, 'learning', 'proposals'))
-      .filter((name) => /^\d{4}-\d{2}\.md$/.test(name))
-  } catch { /* vacío */ }
+  // Sin su línea, el cargo existe pero no se encuentra: quien tiene una tarea tendría que abrir la
+  // carpeta para saber si es éste. Se exige acá y no como advertencia porque es estático y de una línea.
+  const linea = catalog.summary(target)
+  if (!linea) errors.push('SKILL.md no declara summary: la línea con la que se elige este cargo')
+  else if (linea.length > SUMMARY_MAX) {
+    errors.push(`summary tiene ${linea.length} caracteres y el máximo es ${SUMMARY_MAX}: `
+      + 'si no entra en una línea, no sirve para elegir de un vistazo')
+  }
+  const proposals = proposalFiles(path.join(target, 'learning', 'proposals'))
+  let pending = 0
   for (const name of proposals) {
     const text = fs.readFileSync(path.join(target, 'learning', 'proposals', name), 'utf8')
     if (!/^automatic_apply:\s*false$/m.test(text)) errors.push(`${name}: automatic_apply debe ser false`)
     for (const section of REQUIRED_SECTIONS) {
       if (!text.includes(`## ${section}`)) errors.push(`${name}: falta sección ${section}`)
     }
+    // Contar sólo las que esperan algo. Una propuesta aplicada contada como propuesta deja al cargo
+    // reportando trabajo pendiente para siempre, y es la misma confusión que permitía reaplicarla.
+    if (proposalState(text) !== 'applied') pending += 1
   }
   let cases = 0
   try {
     cases = fs.readdirSync(path.join(target, 'evaluations', 'cases'))
       .filter((name) => name.endsWith('.md')).length
   } catch { /* vacío */ }
-  return { errors, proposals: proposals.length, cases }
+  return { errors, proposals: proposals.length, pending, cases }
 }
 
-module.exports = { prepareReport, prepareProposal, evaluate }
+module.exports = { prepareReport, prepareProposal, evaluate, proposalState, seal }

package/engine/automation/index.js

@@ -12,6 +12,11 @@ const M = require('../core/manifest')
 
 const RUNNER_NAMES = ['claude', 'codex', 'gemini', 'antigravity']
 
+// Los guards que el motor implementa, tomados del registro que los ejecuta. Sale de ahí y no de un
+// número escrito a mano: `automation check` anunciaba «11 guards» cuando hacía rato que eran doce, y
+// un conteo que envejece solo es peor que ninguno —dice que revisó menos de lo que revisó—.
+const GUARD_NAMES = Object.keys(H.guards)
+
 // Adaptadores y workflows viven en el paquete, no en la instancia: son definiciones que el motor
 // consume y que ninguna empresa edita —`RUNNER_NAMES` es cerrado, así que ni siquiera puede agregar
 // uno propio—. Los hooks sí se quedan en el proyecto: la configuración del runner los nombra por
@@ -172,7 +177,7 @@ Respetá los límites de ese contrato y las reglas de \`AGENTS.md\`. Generado po
 }
 
 function installRoleSkills(root, runner, output) {
-  if (!runner.capabilities.nativeSkills || !runner.roleSkills) return 0
+  if (!runner.capabilities.nativeSkills || !runner.roleSkills) return
   const install = installRoot(root)
   const base = F.assertWithin(install, path.resolve(install, runner.roleSkills), `${runner.name}: roleSkills`)
   const roles = roleCatalog(root)
@@ -182,7 +187,6 @@ function installRoleSkills(root, runner, output) {
     F.atomicWrite(file, roleSkill(role))
   }
   if (roles.length) output.log(`✓ ${runner.name}: ${roles.length} cargo(s) disponibles en ${runner.roleSkills}`)
-  return roles.length
 }
 
 // Runners que además de los archivos necesitan un registro propio para que el wiring cuente. Copiar
@@ -239,24 +243,7 @@ function check(root) {
   if (!fs.existsSync(path.join(root, 'automatization', 'AGENTS.md'))) {
     errors.push('falta automatization/AGENTS.md')
   }
-  const hooks = [
-    'run-hook.sh',
-    'guard-shell.sh',
-    'guard-files.sh',
-    'guard-destructive.sh',
-    'guard-git-add.sh',
-    'guard-secrets.sh',
-    'guard-generated.sh',
-    'guard-workspace-boundary.sh',
-    'guard-engine.sh',
-    'guard-migrations.sh',
-    'guard-dependencies.sh',
-    'guard-governance.sh',
-    'guard-verify.sh',
-    'guard-planning-drift.sh',
-    'guard-integration-snapshot.sh',
-  ]
-  for (const name of hooks) {
+  for (const name of expectedHooks()) {
     const file = path.join(hookDir, name)
     if (!fs.existsSync(file)) errors.push(`falta automatization/hooks/${name}`)
     else if (!(fs.statSync(file).mode & 0o111)) {
@@ -267,8 +254,12 @@ function check(root) {
   if (!O.engineAt(root, path.join('hooks', 'run.js'))) {
     errors.push('falta engine/hooks/run.js: corré "npm install" en la raíz del repo ops')
   }
-  const workflows = ['autobuild.js', 'team.js', path.join('integrations', 'sync.js')]
-  workflows.push(path.join('integrations', 'promote.js'))
+  const workflows = [
+    'autobuild.js',
+    'team.js',
+    path.join('integrations', 'sync.js'),
+    path.join('integrations', 'promote.js'),
+  ]
   const packaged = packagedAutomation(root)
   for (const name of workflows) {
     if (!packaged || !fs.existsSync(path.join(packaged, 'workflows', name))) {
@@ -308,13 +299,32 @@ function validateRunner(root, name, errors) {
   }
 }
 
+// Un `.sh` por grupo de más de un guard: es el que registra el runner para correrlos en un proceso.
+function groupWrappers() {
+  return Object.entries(H.hookGroups)
+    .filter(([, names]) => names.length > 1)
+    .map(([group]) => [group, `guard-${group.replace('pre-', '')}.sh`])
+}
+
+// Los scripts que la instancia debe tener, derivados del registro que los ejecuta en vez de copiados
+// a mano: la copia envejecía sin avisar, porque un guard nuevo del motor no entraba en la cuenta.
+//
+// Se comprueba en una sola dirección a propósito. Un `.sh` que no está acá no sobra: así es como una
+// empresa agrega el suyo —`guard-acme.sh` al lado de los nuestros—, que es lo que `upgrade` le dice
+// que haga y lo único que sobrevive a cada actualización.
+function expectedHooks() {
+  return [
+    'run-hook.sh',
+    ...groupWrappers().map(([, wrapper]) => wrapper),
+    ...GUARD_NAMES.map((name) => `guard-${name}.sh`),
+  ]
+}
+
 // Guards que hoy viven dentro de un grupo, con el wrapper que los reemplaza.
 function supersededGuards() {
   const entries = []
-  for (const [group, names] of Object.entries(H.hookGroups)) {
-    if (names.length < 2) continue
-    const wrapper = `guard-${group.replace('pre-', '')}.sh`
-    for (const name of names) entries.push({ file: `guard-${name}.sh`, wrapper })
+  for (const [group, wrapper] of groupWrappers()) {
+    for (const name of H.hookGroups[group]) entries.push({ file: `guard-${name}.sh`, wrapper })
   }
   return entries
 }
@@ -469,6 +479,12 @@ function deliveryState(recorded, name, resolved, prefix = '') {
 }
 
 function install(root, name, output = console, options = {}) {
+  // `install` arma la superficie de consumo de una empresa: punteros a cada cargo, una copia de los
+  // workflows y los guards. Acá los cargos y los workflows son el producto —la copia divergiría— y
+  // hay guards que contradicen el trabajo, como el que bloquea el push de cada release.
+  if (O.mode(root) === 'toolkit') {
+    throw new Error('Acá se fabrica Cauce, no se lo consume.')
+  }
   const runner = runnerManifest(root, name)
   const errors = check(root)
   if (errors.length) throw new Error(`La automatización no es instalable:\n- ${errors.join('\n- ')}`)
@@ -550,16 +566,14 @@ function listHooks(output = console) {
 }
 
 module.exports = {
+  GUARD_NAMES,
   RUNNER_NAMES,
   check,
   doctor,
-  includesConfig,
   install,
   legacyGuardWiring,
-  pruneSupersededHooks,
   roleCatalog,
   roleSkill,
   listHooks,
-  mergeConfig,
   runnerManifest,
 }

package/engine/cli/args.js

@@ -0,0 +1,52 @@
+'use strict'
+
+// La gramática de la línea de comandos, en su propio módulo para poder probarla sin ejecutar el
+// CLI: `tools/ops.js` invoca el comando haciendo `require` del motor, así que ops.js corre al ser
+// requerido y no puede exportar nada sin dispararse.
+
+// Banderas que consumen el argumento siguiente: su valor no es un posicional.
+const VALUED_FLAGS = new Set(['--name', '--mode', '--fixture', '--period'])
+
+// Qué acepta cada comando, y a la vez qué comandos existen. Una bandera desconocida se rechaza en vez
+// de ignorarse: `check --jsonn` imprimía la salida humana con código 0, así que quien esperaba JSON
+// —un agente, típicamente— recibía texto sin ninguna señal de que su bandera no existía.
+const FLAGS = {
+  init: ['--name', '--mode', '--force'],
+  check: ['--json'],
+  tree: ['--json', '--no-color'],
+  context: ['--json'],
+  upgrade: ['--check', '--force'],
+  archive: [],
+  agents: ['--json', '--own', '--system'],
+  integration: ['--fixture'],
+  automation: ['--force'],
+  learn: ['--proposal', '--applied', '--period'],
+  evaluate: ['--cases', '--json', '--bench', '--force'],
+  team: ['--json'],
+}
+
+// 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
+// levantar un proceso. Acá se parsea al entrar y lo demás recibe el resultado.
+function parse(argv) {
+  const flags = new Set()
+  const values = {}
+  const positional = []
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]
+    if (!value.startsWith('--')) { positional.push(value); continue }
+    flags.add(value)
+    if (VALUED_FLAGS.has(value)) { values[value] = argv[index + 1] || ''; index += 1 }
+  }
+  return {
+    positional,
+    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)),
+  }
+}
+
+module.exports = { FLAGS, VALUED_FLAGS, parse }