@ingeniomaps/cauce 0.90.0 → 0.92.0

package/engine/cli/catalog.js

@@ -3,16 +3,16 @@
 // Los comandos sobre el catálogo: qué cargos y equipos hay, qué aprenden y cómo se los mide. Todos
 // resuelven la raíz ops de la misma forma, que es lo que los junta acá.
 
-const fs = require('node:fs')
 const path = require('node:path')
-const { spawnSync } = require('node:child_process')
 const L = require('../agents/learning')
 const LF = require('../agents/learning-files')
 const AG = require('../agents/catalog')
 const EV = require('../agents/evaluations')
 const T = require('../flows/registry')
 const O = require('../core/ownership')
-const IN = require('./instance')
+// 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')
 
 function agentsFork(slug, dir) {
@@ -67,169 +67,6 @@ function agents(action, dir, extra, cli) {
   }
 }
 
-// Qué decir cuando el banco sobrevivió a su propio borrado, que es lo único que va a permitir
-// establecer la causa. Devuelve el mensaje en vez de escribirlo donde ocurre, y eso es lo que lo hace
-// medible sin provocar el fallo; por qué eso importa acá lo dice su prueba.
-//
-// Tres cosas que el listado anterior no traía, y cada una separa dos diagnósticos distintos:
-//
-// - **Cuánto**, y no una muestra. Cortaba en cinco, así que «borró casi todo y quedaron cuatro objetos»
-//   y «no borró nada» se leían idénticos, y son problemas opuestos.
-// - **Si lo que quedó es anterior al borrado o se escribió durante.** Posterior significa que alguien
-//   reescribió mientras borrábamos; anterior, que el borrado no lo tocó. Es la pregunta central del
-//   caso y la contesta la fecha de modificación.
-// - **Qué hace un segundo borrado.** No lo rodea: quien lo llama corta igual.
-//   Distingue lo transitorio de lo permanente, que se arreglan distinto.
-function benchSurvived(dir, since) {
-  let files = 0
-  let dirs = 0
-  const sample = []
-  const walk = (base, relative = '') => {
-    for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
-      const next = relative ? `${relative}/${entry.name}` : entry.name
-      if (entry.isDirectory()) { dirs += 1; walk(path.join(base, entry.name), next); continue }
-      files += 1
-      if (sample.length >= 5) continue
-      const stat = fs.statSync(path.join(base, entry.name), { throwIfNoEntry: false })
-      sample.push(`${next} (${!stat ? 'ya no está'
-        : stat.mtimeMs >= since ? 'escrito durante el borrado' : 'anterior al borrado'})`)
-    }
-  }
-  try { walk(dir) } catch { /* el listado es la explicación, no la comprobación */ }
-  let again = 'no se pudo reintentar'
-  try {
-    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 })
-    again = fs.existsSync(dir) ? 'un segundo borrado tampoco lo sacó' : 'un segundo borrado sí lo sacó'
-  } catch (error) { again = `un segundo borrado lanzó ${error.code || error.message}` }
-  return `${dir} no se pudo borrar entero y el banco tiene que ser nuevo. Sobrevivieron ${files} `
-    + `archivo(s) en ${dirs} directorio(s), con Node ${process.version}: `
-    + `${sample.join(', ') || '(sólo directorios)'}. ${again}. Borralo a mano y volvé a correr.`
-}
-
-// Borrar el banco y comprobar que se borró, que es una sola decisión: lo que no desapareció contamina la
-// medición que viene. Devuelve el motivo en vez de cortar —quien corta es el comando— y así se puede medir.
-//
-// **El destino se comprueba antes de destruir** (R23). `dir` lo arma este archivo a partir de nombres ya
-// validados, así que hoy no puede apuntar afuera; la comprobación existe porque el costo de que algún día
-// pueda no es un resultado incorrecto sino trabajo perdido, y porque una ruta peligrosa se construye sola
-// a partir de algo vacío. Se niega nombrando la ruta y contra qué la comparó.
-//
-// `remove` se inyecta porque **la condición que la comprobación de abajo existe para atrapar no se puede
-// provocar con el sistema de archivos real**: es el caso 078, y sin ese hueco la línea que decide se
-// quedaba sin una sola prueba —comprobado: borrarla no ponía nada en rojo—. Con un borrado que no borra,
-// 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.`
-  }
-  // 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.
-  const since = Date.now()
-  // Con reintentos. Los puso el `ENOTEMPTY` que aparecía al rehacer un banco recién creado, y hoy se sabe
-  // que eso era el mantenimiento de git escribiendo por detrás (caso 073). Se quedan porque son lo único
-  // que corre **antes** de la comprobación: cubren a cualquier otro escritor transitorio, no a éste, que
-  // está apagado.
-  remove(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 })
-  return fs.existsSync(target) ? benchSurvived(target, since) : null
-}
-
-// Un banco de trabajo desechable donde un cargo del catálogo puede realmente trabajar.
-//
-// Hace falta porque el toolkit no es una raíz ops: el único `planning/` que vive acá es
-// `template/planning`, el molde que se distribuye. Un cargo cuya entrega es una épica no tiene dónde
-// escribir, así que se niega —con razón—, y su caso cuenta como fallo: eso midió una configuración.
-//
-// Uno por caso, y se aprendió corriendo: con un banco compartido los casos se leen entre sí, y uno
-// tomó por «una sesión anterior de este mismo cargo» lo que otro acababa de escribir. La
-// independencia entre casos es la premisa de medir con ellos.
-//
-// Se recrea entero en cada corrida —si no, lo que escribió el lunes es contexto del martes— y queda
-// en disco, gitignorado: después de un veredicto raro uno quiere mirar qué escribió el cargo.
-function evaluationBench(root, agent, caso, force, kind) {
-  const safe = (value) => {
-    if (!/^[a-z0-9_][a-z0-9._-]*$/i.test(value) || value.includes('..')) {
-      fail(`nombre inválido para el banco: ${value}`, 2)
-    }
-    return value
-  }
-  const dir = path.join(root, '.cauce-eval', safe(agent), safe(caso || '_libre'))
-  // Recrear un banco donde alguien ya trabajó borra la evidencia de esa corrida, y el registro de la
-  // evaluación se escribe **desde** el banco. Pasó de verdad: se rehizo un banco para probar otra cosa
-  // y con él se fue lo que el cargo había escrito; el juez leyó un directorio vacío y concluyó que la
-  // respuesta afirmaba algo inexistente. Con el banco versionado, «acá se trabajó» es una pregunta que
-  // git contesta exacto.
-  const dirty = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' })
-  if ((dirty.stdout || '').trim() && !force) {
-    fail(`${dir} tiene trabajo sin recoger. Guardá el registro de esa corrida antes de rehacerlo, `
-      + 'o usá --force si ya lo tenés.', 2)
-  }
-  // Rodear un borrado a medias deja la corrida siguiendo sobre un banco que no es nuevo, y lo que falla
-  // después no dice nada del borrado: el test que lo destapó reportaba `true !== false` sobre un archivo
-  // de la corrida anterior, sin nombrar de dónde salía. Esta guarda es la que estableció la causa —su
-  // primer disparo instrumentado nombró al escritor—; lo que cubre ahora es que aparezca otro.
-  //
-  // **Y de acá para abajo el directorio no existe.** Eso es lo que sostiene que el andamiaje y el enlace
-  // se escriban sin defensas: hasta el 073, los dos llevaban una por si algo sobrevivía al borrado.
-  const problema = clearBench(dir, path.join(root, '.cauce-eval'))
-  if (problema) fail(problema, 2)
-  // Sin `force`, y eso es lo que hay que poder decir: sólo servía si algún archivo sobrevivía al borrado,
-  // y la comprobación de arriba garantiza que no queda ninguno. Lo llevaba porque el mismo test falló tres
-  // veces en un día con «El destino contiene …/AGENTS.md», y eso era el escritor de fondo que apagó el 073.
-  IN.scaffold(dir, { name: 'Banco de evaluación', mode: 'sidecar', quiet: true })
-  // El motor por symlink: la misma resolución que en una instancia real —`node_modules/@ingeniomaps`—
-  // sin pagar un `npm install` por corrida. El cargo llega a un banco donde el CLI funciona.
-  const scope = path.join(dir, 'node_modules', '@ingeniomaps')
-  fs.mkdirSync(scope, { recursive: true })
-  // Y el enlace se crea sin borrarlo antes, por lo mismo: `scope` acaba de nacer dentro de un directorio
-  // que no existía, así que no puede haber un enlace que pisar. El `rm` que había acá era el tercer rodeo
-  // del mismo escritor de fondo, y el que falló en CI con `EEXIST`.
-  const link = path.join(scope, 'cauce')
-  fs.symlinkSync(IN.PROJECT_ROOT, link, 'dir')
-
-  // El artefacto del caso, si lo tiene: la guía del proveedor que el pedido manda implementar, el CSV
-  // con instrucciones adentro. Entra antes del commit limpio a propósito — si entrara después, `status`
-  // se lo atribuiría al cargo y el juez leería como obra suya el documento que vino a resistir.
-  if (caso) {
-    const fixture = EV.fixtures(root, agent, caso, kind)
-    if (fixture.files.length) fs.cpSync(fixture.dir, dir, { recursive: true })
-  }
-
-  // Versionado desde su estado limpio porque la entrega de un cargo puede no estar en su respuesta:
-  // uno contestó un resumen y escribió el contrato entero en su `INBOX.md`, y el juez —que sólo leía
-  // la respuesta— lo dio por ausente. Con git, `status` y `diff` muestran qué produjo, separado del
-  // andamiaje. Se ignora `node_modules`: es un symlink al toolkit, no obra del cargo.
-  // `-C` dice dónde mirar y `GIT_DIR` gana igual —comprobado: con `GIT_DIR` puesto,
-  // `git -C otro rev-parse --absolute-git-dir` contesta el de la variable—, así que sin limpiarla el
-  // banco commitea en el repositorio que la haya exportado. Es lo que hizo el caso 045 antes de
-  // arreglarse en `hooks/shell.js`: el banco de una evaluación dejó sus commits en la rama del usuario.
-  const env = { ...process.env }
-  delete env.GIT_DIR
-  delete env.GIT_WORK_TREE
-  const git = (...args) => spawnSync('git', ['-C', dir, ...args], { stdio: 'ignore', env })
-  fs.appendFileSync(path.join(dir, '.gitignore'), '\nnode_modules/\n')
-  git('init', '-q')
-  git('config', 'user.email', 'banco@cauce.local')
-  git('config', 'user.name', 'banco de evaluación')
-  // Y se le apaga el mantenimiento automático, que es el escritor de fondo que rompía el borrado del
-  // banco siguiente. `git commit` lanza `git maintenance run --auto`, que se detacha y sigue escribiendo
-  // en `.git/objects` después de que el comando ya volvió; el banco se rehace milisegundos más tarde y
-  // el `rmSync` corre contra alguien que está escribiendo ahí.
-  //
-  // Es lo que produjo los tres síntomas que se venían rodeando por separado —`ENOTEMPTY`, `EEXIST`, y el
-  // borrado que vuelve sin lanzar y deja archivos—. La guarda lo nombró el 2026-09-10:
-  // `maintenance.lock` entre los sobrevivientes, y `info/refs` y `objects/info/packs` fechados **durante**
-  // el borrado, en un árbol que ninguna otra prueba toca (caso 073).
-  //
-  // `maintenance.auto=false` y no `gc.auto=0`: medido con `GIT_TRACE=1`, el segundo deja que el commit
-  // lance el mantenimiento igual —sólo hace que su tarea de `gc` no encuentre trabajo— y el proceso
-  // toma su lock y escribe lo mismo. Se le quita el motivo de lanzarlo, no lo que hace una vez lanzado.
-  git('config', 'maintenance.auto', 'false')
-  git('add', '-A')
-  git('commit', '-q', '-m', 'banco limpio')
-  return dir
-}
 
 function learn(agent, cli) {
   try {
@@ -321,7 +158,7 @@ function evaluate(agent, caso, cli) {
     // y de ahí la ruta viaja a los informes y a las propuestas que después lee otro cargo. Absoluta
     // nombraba el directorio personal de una máquina, y así quedaron mil cuatrocientas ochenta y cinco
     // citas que dejaron de resolver el día que este repositorio cambió de nombre.
-    return console.log(path.relative(root, evaluationBench(root, agent, caso, cli.has('--force'), kind)))
+    return console.log(path.relative(root, B.evaluationBench(root, agent, caso, cli.has('--force'), kind)))
   }
   try {
     // Los casos, para que un recorrido los ejecute. Sin `--json` no tiene sentido: es entrada de
@@ -420,4 +257,6 @@ function flow(action, slug, cli) {
   } catch (error) { fail(error.message, 2) }
 }
 
-module.exports = { agents, learn, evaluate, flow, benchSurvived, clearBench }
+module.exports = {
+  agents, learn, evaluate, flow, benchSurvived: B.benchSurvived, clearBench: B.clearBench,
+}

package/engine/cli/contract.js

@@ -0,0 +1,200 @@
+'use strict'
+
+// El contrato del proyecto, derivado del disco. Es lo que un recorrido necesita saber antes de la primera
+// fase —cómo se llama el proyecto, dónde puede escribir, con qué se verifica, qué límites rigen y qué
+// formatos exige planning— y hasta 0.91.0 lo producía un agente que leía cuatro archivos y los transcribía.
+//
+// Transcribir no es decidir: los diez campos salen de parsear. Seis son valores de `ops.config.json`, uno
+// es copiar una sección de `PROTOCOL.md` y dos son secciones de `AGENTS.md` y `organization/workspace.md`.
+// Pagarle a un modelo por eso cuesta una llamada por corrida y, sobre todo, hace que lo que viaja al
+// preámbulo de cada subagente sea **lo que alguien transcribió** en vez de lo que el archivo dice (caso 154).
+//
+// El porqué de resolverlo con un comando y no con un agente ya está escrito donde se decidió la primera
+// vez: el comentario de `readContext`, en el recorrido. Acá sólo se repite la elección, no su razón.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const P = require('../planning/parser')
+const { fail, opsRoot } = require('./io')
+
+// Los cuatro que componen el contrato, con la ruta relativa a la raíz de la instancia. El orden es el que
+// usa el mensaje de error: se nombra el primero que falte y no los cuatro, porque arreglar uno suele
+// arreglar la causa de los demás —una raíz mal apuntada los pierde todos a la vez—.
+const SOURCES = ['AGENTS.md', path.join('organization', 'workspace.md'), 'ops.config.json',
+  path.join('planning', 'PROTOCOL.md')]
+
+// Qué sección sostiene cada campo de texto, y de quién es el archivo que la trae. La diferencia decide qué
+// pasa cuando falta, y no es una preferencia: `AGENTS.md` y `PROTOCOL.md` están en `TEMPLATE_FILES`, así que
+// `upgrade` los reemplaza enteros y su sección no puede faltar en una instancia viva —si falta, algo se
+// rompió y seguir entregaría límites vacíos a cada subagente—. `organization/workspace.md` es del proyecto:
+// que no declare excepciones es un estado legítimo y el molde lo dice.
+const REQUIRED_SECTIONS = [
+  { file: 'AGENTS.md', heading: /Autonom/, name: '## Autonomía' },
+  { file: path.join('planning', 'PROTOCOL.md'), heading: /Contratos/, name: '## Contratos' },
+]
+
+const readIfAny = (file) => {
+  try { return fs.readFileSync(file, 'utf8') } catch { return '' }
+}
+
+// Con qué arranca un párrafo que **enuncia** un límite, frente a uno que lo explica. Es vocabulario
+// cerrado, igual que `lane` o `blocked`, y por la misma razón: lo que sigue es una lista de la que un
+// agente tiene que poder obedecer cada entrada, y una heurística abierta admite cualquier cosa.
+const ENUNCIA = /^(?:El runner\b|Debe\b|Nunca\b)/
+// Un límite por entrada y no la sección cruda. `SCOPE()` las une con `; ` en una sola frase del preámbulo
+// que se reenvía a **cada** subagente, así que el tamaño no se paga una vez: volcar ahí los dos mil bytes
+// de la sección entera metía encabezados, conectores —«Eso rige sin que nadie escriba nada.»— y los
+// párrafos que razonan sobre `BR-OPS-002` y `runner.allowPush`, que son prosa para una persona.
+//
+// Se corta por párrafo y por su sujeto, no por posición ni por oración. Partir por oración fue el primer
+// intento y devolvía diecisiete entradas de las que cuatro eran límites; por posición habría funcionado
+// sobre el molde de hoy y se habría roto con el primero que agregue un párrafo.
+//
+// Lo que esto no resuelve, y por eso existe el caso 157: que sea una deducción gramatical y no una marca.
+// Un límite que el proyecto escriba con otra forma no entra, y eso no se ve — la lista sale más corta y se
+// lee igual de completa. Sobre `AGENTS.md` casi no puede pasar porque `upgrade` lo reemplaza entero; sobre
+// `organization/workspace.md`, que lo escribe una persona, pasa siempre que no imite esta gramática.
+// Y el camino declarado, que es el que no adivina: una viñeta bajo `### Límites`. El molde lo trae desde
+// 0.92.0 para que quien escriba una excepción tenga dónde ponerla en vez de tener que imitar la gramática
+// de arriba (caso 157).
+//
+// Los dos caminos conviven a propósito. Quitar `ENUNCIA` al agregar la marca dejaría de contar lo ya
+// escrito en instancias vivas —que es la decisión que el caso pedía tomar sobre lo existente—, y así no
+// hay nada que migrar: lo viejo sigue entrando, lo nuevo entra mejor, y lo que no entra por ninguno lo
+// reporta `warnings`.
+const MARKED = /^###\s+Límites\s*$/m
+
+// Se recorren **todos** los bloques `### Límites`, no el primero. El molde ya trae uno con su ejemplo,
+// así que quien agregue el suyo al final del archivo —que es lo que hace cualquiera— queda con dos, y
+// leer sólo el primero devolvía cero viñetas: el límite del proyecto no llegaba y el aviso tampoco lo
+// veía, porque para la comparación caía dentro de la sección del molde.
+//
+// No filtra comentarios y no hace falta: una viñeta comentada arranca con `<!--`, así que el filtro de
+// viñetas ya la descarta. Sacar `withoutComments` de acá fue el resultado de una mutación que sobrevivió
+// —apagarlo no ponía nada en rojo—, que es como se ve una defensa que no defiende de nada.
+function declared(raw) {
+  const out = []
+  let rest = raw
+  for (let start = rest.search(MARKED); start >= 0; start = rest.search(MARKED)) {
+    const after = rest.slice(start).split('\n').slice(1)
+    const end = after.findIndex((line) => /^#{1,3}\s/.test(line))
+    const block = end < 0 ? after : after.slice(0, end)
+    out.push(...block
+      .filter((line) => /^\s*[-*]\s+/.test(line))
+      .map((line) => line.replace(/^\s*[-*]\s+/, '').trim())
+      .filter(Boolean))
+    rest = (end < 0 ? '' : after.slice(end).join('\n'))
+  }
+  return out
+}
+
+function limits(text) {
+  const prose = text.split(/\n\s*\n/)
+    .map((block) => block.split('\n')
+      .map((line) => line.replace(/^[-*]\s+/, '').trim())
+      .filter((line) => line && !line.startsWith('#') && !line.startsWith('|'))
+      .join(' ')
+      .trim())
+    .filter((block) => ENUNCIA.test(block))
+  return [...declared(text), ...prose]
+}
+
+// Lo que el proyecto escribió en su sección de excepciones y **no** llegó a `boundaries`. Existe porque
+// perder un límite acá no se ve: la lista sale más corta y se lee igual de completa, y el preámbulo de
+// cada subagente sigue afirmando «Límites del proyecto: …» con los que sí matcharon (caso 157).
+//
+// Lo que cuenta como «escrito por el proyecto» no se deduce de la gramática —sería el mismo defecto con
+// otra cara—: se compara contra el molde, que viaja en el paquete. Un párrafo que el molde no trae lo
+// puso alguien de este proyecto, y si además no enuncia, es exactamente lo que se está perdiendo.
+//
+// No avisa de la sección vacía, que es el caso fácil y el que menos importa: el caro es encontrar dos de
+// tres, y ése sólo se ve comparando párrafo por párrafo.
+const TEMPLATE_WORKSPACE = path.join(__dirname, '..', '..', 'template', 'organization', 'workspace.md')
+
+const paragraphs = (text) => text.split(/\n\s*\n/)
+  .map((block) => block.split('\n')
+    .map((line) => line.replace(/^[-*]\s+/, '').trim())
+    .filter((line) => line && !line.startsWith('#') && !line.startsWith('|'))
+    .join(' ')
+    .trim())
+  .filter(Boolean)
+
+function warnings(root) {
+  const mine = P.section(readIfAny(path.join(root, 'organization', 'workspace.md')),
+    /Excepciones de autonom/)
+  if (!mine.trim()) return []
+  // Sin comentarios de los dos lados: el ejemplo del molde viene comentado, y contarlo como párrafo lo
+  // volvería un aviso permanente sobre algo que nadie escribió.
+  const fromTemplate = new Set(paragraphs(
+    P.withoutComments(P.section(readIfAny(TEMPLATE_WORKSPACE), /Excepciones de autonom/)),
+  ))
+  const declaredHere = new Set(declared(mine))
+  const lost = paragraphs(P.withoutComments(mine))
+    .filter((one) => !fromTemplate.has(one) && !ENUNCIA.test(one) && !declaredHere.has(one))
+  if (!lost.length) return []
+  return [`organization/workspace.md: ${lost.length} párrafo(s) de "## Excepciones de autonomía" no llegan `
+    + 'a los agentes porque no arrancan con «El runner», «Debe» o «Nunca»: '
+    + `${lost.map((one) => `"${one.slice(0, 60)}…"`).join(', ')}`]
+}
+
+function contract(dir, cli) {
+  const root = opsRoot(dir)
+  const missing = SOURCES.find((name) => !fs.existsSync(path.join(root, name)))
+  // Sin los cuatro no hay contrato que derivar, y contestar uno a medias es peor que no contestar: lo que
+  // se pierde no se ve en la salida, se ve tres fases después en lo que un subagente creyó que podía tocar.
+  if (missing) {
+    return fail(`${root} no tiene ${missing}, así que no hay contrato que derivar. Es la raíz que escribió `
+      + '`automation install`: comprobá que exista y, si moviste el proyecto de carpeta, reinstalá el adaptador.', 2)
+  }
+
+  let config
+  try {
+    config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
+  } catch (error) {
+    return fail(`ops.config.json no se pudo leer como JSON: ${error.message}`, 2)
+  }
+
+  const sections = {}
+  for (const { file, heading, name } of REQUIRED_SECTIONS) {
+    const found = P.section(readIfAny(path.join(root, file)), heading)
+    // Nombrar la sección y el archivo es lo que separa este error de «algo salió mal»: quien lo lee tiene
+    // que poder abrir el archivo y ver qué encabezado falta, y el arreglo es restaurarlo con `upgrade`.
+    if (!found.trim()) {
+      return fail(`${file} no tiene la sección ${name}, y de ahí sale el contrato que reciben los agentes. `
+        + 'Ese archivo lo reemplaza `ops upgrade` entero: corrélo para restaurarlo.', 2)
+    }
+    sections[file] = found
+  }
+
+  const roots = Array.isArray(config.workspaceRoots) ? config.workspaceRoots : []
+  const runner = config.runner || {}
+  const excepciones = P.section(readIfAny(path.join(root, 'organization', 'workspace.md')),
+    /Excepciones de autonom/)
+  const report = {
+    rootOk: true,
+    project: String(config.project || ''),
+    // «nombre → ruta», que es la forma con la que el preámbulo las enumera como límite de escritura.
+    workspaceRoots: roots.filter((one) => one && one.name && one.path).map((one) => `${one.name} → ${one.path}`),
+    // Una entrada por raíz que declare `verify`, y ninguna por las que no: la lista vacía significa que el
+    // proyecto no dice con qué se verifica, que es distinto de no haberlo mirado.
+    gates: roots.filter((one) => one && one.path && one.verify).map((one) => `${one.path} → ${one.verify}`),
+    maxTaskHours: Number(runner.maxTaskHours || 0),
+    commitPerTask: Boolean(runner.commitPerTask),
+    humanCheckpoint: Boolean(runner.humanCheckpointBetweenMilestones),
+    // Textual y sin reformular: es el formato contra el que se escribe roadmap, BACKLOG, WIP y DONE, y un
+    // resumen de un formato no sirve para cumplirlo.
+    contracts: sections[path.join('planning', 'PROTOCOL.md')].trim(),
+    // Los del toolkit primero y los del proyecto después, que es el orden en que se leen: lo segundo amplía
+    // o restringe lo primero, y al revés se leería como si el proyecto fijara la base.
+    boundaries: [...limits(sections['AGENTS.md']), ...limits(excepciones)],
+  }
+  if (cli.has('--json')) return console.log(JSON.stringify(report))
+  console.log(`${report.project}  (${report.workspaceRoots.join('; ') || 'sin raíces declaradas'})`)
+  console.log(`gates      ${report.gates.join('; ') || 'ninguno declarado'}`)
+  console.log(`runner     ${report.maxTaskHours} h por tarea · `
+    + `commit ${report.commitPerTask ? 'por tarea' : 'libre'} · `
+    + `checkpoint ${report.humanCheckpoint ? 'entre hitos' : 'no'}`)
+  console.log(`límites    ${report.boundaries.length} · contratos ${report.contracts.length} caracteres`)
+}
+
+module.exports = { contract, warnings }

package/engine/cli/ops.js

@@ -9,6 +9,8 @@ const { FLAGS, parse } = require('./args')
 const { fail } = require('./io')
 const IN = require('./instance')
 const PL = require('./planning')
+const CT = require('./contract')
+const BN = require('./bench')
 const VA = require('./validate')
 const AR = require('./archive')
 const CLM = require('./claims')
@@ -149,6 +151,8 @@ function usage() {
   ops check <planning-dir> [--json]
   ops tree <planning-dir> [--no-color] [--json]
   ops context <planning-dir> [--hito <slug>] [--json]
+  ops contract <ops-root> [--json]
+  ops bench <suelto|tarea|sidecar> [--force]
   ops recurring <planning-dir> [--promote <qué>] [--json]
   ops runners <planning-dir> [--json]
   ops claim <planning-dir> <tarea>
@@ -208,6 +212,8 @@ async function run(cli) {
   else if (command === 'check') VA.check(arg[1], cli)
   else if (command === 'tree') PL.tree(arg[1], cli)
   else if (command === 'context') PL.context(arg[1], cli)
+  else if (command === 'contract') CT.contract(arg[1], cli)
+  else if (command === 'bench') BN.bench(arg[1], cli)
   else if (command === 'recurring') PL.recurring(arg[1], cli)
   else if (command === 'runners') CLM.runners(arg[1], cli)
   else if (command === 'claim') CLM.claim(arg[1], arg[2], cli)

package/engine/cli/validate.js

@@ -29,6 +29,7 @@ const C = require('../config/validate')
 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')
 
 function check(dir, cli) {
@@ -131,6 +132,7 @@ function check(dir, cli) {
   warnings.push(...R.unrecordedHumanActions(path.resolve(root, '..'), P.readHumanActions(root)))
   warnings.push(...AP.warnings(path.resolve(root, '..')))
   warnings.push(...TR.warnings(path.resolve(root, '..')))
+  warnings.push(...CT.warnings(path.resolve(root, '..')))
 
   // 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

package/engine/config/validate.js

@@ -121,7 +121,7 @@ function validateWorkspaces(workspaces, errors) {
       continue
     }
     for (const key of Object.keys(workspace)) {
-      if (!['name', 'path', 'verify'].includes(key)) {
+      if (!['name', 'path', 'verify', 'scope'].includes(key)) {
         errors.push(`ops.config.json: workspaceRoots[${index}].${key} no está permitido`)
       }
     }
@@ -130,6 +130,18 @@ function validateWorkspaces(workspaces, errors) {
     if ('verify' in workspace && (typeof workspace.verify !== 'string' || !workspace.verify.trim())) {
       errors.push(`ops.config.json: workspaceRoots[${index}].verify debe ser el comando, o no estar`)
     }
+    // Qué rutas lee esa puerta, y se rechaza vacío por lo que dice la línea de arriba. Lo propio de acá
+    // es que ausente **no** es lo mismo que vacío: sin el campo cuenta cualquier delta, que es lo que
+    // mantiene válida a toda instancia escrita antes de que existiera, mientras que una lista vacía diría
+    // que la puerta no lee nada y ningún delta la alcanzaría nunca.
+    if ('scope' in workspace) {
+      const scope = workspace.scope
+      if (!Array.isArray(scope) || !scope.length) {
+        errors.push(`ops.config.json: workspaceRoots[${index}].scope debe ser una lista de rutas, o no estar`)
+      } else if (scope.some((one) => typeof one !== 'string' || !one.trim())) {
+        errors.push(`ops.config.json: workspaceRoots[${index}].scope: cada entrada es un patrón de ruta`)
+      }
+    }
     if (typeof workspace.name !== 'string' || !workspace.name.trim()) {
       errors.push(`ops.config.json: workspaceRoots[${index}].name es obligatorio`)
     }

package/engine/core/ownership.js

@@ -107,10 +107,37 @@ function sourceOf(relative) {
 // Dos caminos, no tres. La copia vendorizada en `.ops/` se retiró en 0.10.0 — ahorraba un
 // `package.json` a cambio de 5 MB en la historia de la empresa y de no poder enterarse de una versión
 // nueva, y Node hace falta igual en los dos casos.
+//
+// Y un tercero, que es el layout que produce el flujo documentado: `npm install @ingeniomaps/cauce` se
+// corre en la carpeta de la empresa y `cauce init ops` deja la instancia adentro, así que el motor queda
+// **arriba** de ella. Sin este candidato, `automation check` daba nueve errores sobre un motor instalado y
+// el consejo mandaba a bajar una segunda copia un nivel más abajo (caso 158).
+//
+// Un nivel y no una búsqueda hacia arriba. Node sube hasta la raíz del disco y eso acá adivina: dentro de
+// un monorepo con varios paquetes encontraría un motor de otra versión, y ese fallo es silencioso. Lo que
+// se mira es la raíz que la instancia **declara** —la misma que `installRoot` usa para el runner—, así que
+// un `<empresa>-ops` con su propio `node_modules` gana en el primer candidato y no cambia nada.
+//
+// Se lee acá y no se importa de `automation/runners`: ese módulo ya importa éste, y al revés se muerden.
+//
+// **Y esta cascada la repiten otros dos**, porque corren antes de poder cargar este módulo: el shim
+// `automatization/hooks/run-hook.sh`, que lanza cada guard, y el bridge
+// `automatization/runners/antigravity/hook.js`. Los tres se cambian juntos o el motor se encuentra desde
+// el CLI y no desde los guards, que es medio arreglo y del lado que no se nota.
+function declaredRoot(root) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
+    if (config.mode === 'sidecar') return path.resolve(root, '..')
+  } catch { /* sin configuración legible, sólo el propio */ }
+  return ''
+}
+
 function packagePath(root, relative) {
+  const above = declaredRoot(root)
   const candidates = [
     path.join(root, 'node_modules', '@ingeniomaps', 'cauce', relative),
     path.join(root, relative),
+    ...(above ? [path.join(above, 'node_modules', '@ingeniomaps', 'cauce', relative)] : []),
   ]
   return candidates.find((candidate) => fs.existsSync(candidate)) || ''
 }

package/engine/core/scope.js

@@ -0,0 +1,130 @@
+'use strict'
+
+// Qué rutas alcanza la puerta de una raíz, para poder decidir si un delta puede cambiar su veredicto.
+//
+// Existe porque `verify` declara **el comando** de la puerta y no lo que ese comando lee, así que
+// `commitTree` sólo podía preguntarse *si hay* delta y nunca *qué* delta: cualquier archivo sucio
+// —un README a medio escribir, la basura de una sonda— forzaba la copia del índice aunque el gate no
+// lo fuera a abrir nunca (caso 156). Lo caro no es la copia sino lo que arrastra: adentro
+// `node_modules` viaja por enlace y eso rompe cualquier build de Turbopack (caso 153).
+//
+// Vive en `core/` y recibe las raíces ya leídas: resolver la raíz ops es de `hooks/`, y hacerlo acá
+// invertiría la única dirección de dependencia que el repositorio sostiene entera.
+//
+// El matcher es propio y mínimo, y eso es una decisión: el motor no tiene ninguno reusable —las once
+// construcciones de `RegExp` que hay son para comandos de git, para el chat o para nombres de archivo
+// generado— y agregar una dependencia para esto contradiría la primera convención del repositorio.
+
+const path = require('node:path')
+
+// Lo que un patrón puede traer y hay que neutralizar para que no signifique otra cosa dentro de la
+// expresión regular. `*` y `?` se tratan aparte porque son justamente los que sí significan. Sin esto
+// `package.json` aceptaría `packageXjson`, y el alcance sería más ancho que el declarado.
+const ESCAPE = /[.+^${}()|[\]\\]/g
+
+// El vocabulario es el mínimo que alguien espera al escribir una ruta, y no el de una shell:
+//
+//   `**`  cualquier cantidad de segmentos, incluido ninguno
+//   `*`   cualquier cosa dentro de **un** segmento — no cruza `/`
+//   `?`   un carácter, tampoco `/`
+//
+// No hay llaves ni clases de caracteres, y eso es a propósito: cada forma que se agrega es una forma
+// más de escribir mal un alcance, y un alcance escrito de menos apaga el aislamiento sin que nada lo
+// diga. Se agregan cuando alguien las necesite de verdad.
+//
+// `**/` se consume junto con su barra para que `src/**/x.js` acepte también `src/x.js`: si no, el
+// patrón pediría un directorio intermedio obligatorio, que no es lo que nadie quiere decir.
+function toRegExp(pattern) {
+  let out = ''
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char === '*' && pattern[index + 1] === '*') {
+      const slash = pattern[index + 2] === '/'
+      out += slash ? '(?:.*/)?' : '.*'
+      index += slash ? 2 : 1
+      continue
+    }
+    if (char === '*') { out += '[^/]*'; continue }
+    if (char === '?') { out += '[^/]'; continue }
+    out += char.replace(ESCAPE, '\\$&')
+  }
+  return new RegExp(`^${out}$`)
+}
+
+// La ruta relativa a la raíz declarada, que es donde vive quien escribió el patrón: en un monorepo el
+// `scope` de `apps/web` habla de `src/**`, no de `apps/web/src/**`. Devuelve `null` cuando cae fuera de
+// esa raíz, que no es lo mismo que no coincidir con ningún patrón — una es «no es tuya» y la otra «es
+// tuya y no la mirás».
+//
+// `path.relative` normaliza la barra final —`build/` vuelve como `build`—, así que si hace falta saber
+// que era un directorio hay que mirarlo antes, en la cadena cruda. Eso costó una prueba en rojo.
+function relativeTo(rootDir, repoDir, file) {
+  const absolute = path.resolve(repoDir, file)
+  const inside = path.relative(rootDir, absolute)
+  if (!inside || inside.startsWith('..') || path.isAbsolute(inside)) return null
+  return inside.split(path.sep).join('/')
+}
+
+// Un directorio sin trackear llega como `build/` y **git no dice qué hay adentro**. Si el alcance
+// declara `build/**/*.ts`, ninguna forma del directorio matchea, y quedarse con eso sería dejar de
+// materializar sin saber qué contiene. Por eso cuenta también cuando algún patrón **apunta hacia
+// adentro** de él: equivocarse hacia materializar de más devuelve el comportamiento de siempre;
+// hacia materializar de menos devuelve el defecto que `commitTree` fue a cerrar.
+function coversDirectory(relative, patterns, raw) {
+  const clean = relative.replace(/\/$/, '')
+  const forms = [clean, `${clean}/`]
+  if (forms.some((form) => patterns.some((one) => one.test(form)))) return true
+  return raw.some((pattern) => pattern.startsWith(`${clean}/`))
+}
+
+// La ruta de una línea de `git status --porcelain`: empieza en la columna 4 —`XY ` y después el
+// nombre— y un rename llega como `viejo -> nuevo`, del que importa el destino, que es lo que queda en
+// disco. Las comillas las pone git cuando el nombre trae caracteres raros.
+const fileOf = (line) => line.slice(3).trim().replace(/^.* -> /, '').replace(/^"|"$/g, '')
+
+// Si alguna de las rutas del delta cae dentro del alcance declarado de alguna raíz.
+//
+// **Sin ninguna raíz que declare `scope`, contesta siempre que sí**, y ahí está la compatibilidad: una
+// instancia que no adopta el campo se comporta exactamente como antes de que existiera. Es la única
+// respuesta segura, porque lo que se decide es si se puede confiar en el árbol, y el default tiene que
+// ser el que no confía.
+//
+// Una ruta que no cae bajo **ninguna** raíz declarada también cuenta como adentro: puede ser de la
+// instancia, de otro servicio sin declarar o de la raíz misma, y decidir que no cuenta sería la clase
+// de suposición que este campo existe para no tener que hacer.
+function reachesGate(roots, repoDir, files) {
+  const declared = roots.filter((one) => one && Array.isArray(one.scope) && one.scope.length)
+  if (!declared.length) return true
+  const compiled = declared.map((one) => ({
+    dir: path.resolve(repoDir, one.path),
+    raw: one.scope,
+    patterns: one.scope.map(toRegExp),
+  }))
+  return files.some((file) => {
+    const isDir = file.endsWith('/')
+    let owned = false
+    for (const root of compiled) {
+      const relative = relativeTo(root.dir, repoDir, file)
+      if (relative === null) continue
+      owned = true
+      const hit = isDir
+        ? coversDirectory(relative, root.patterns, root.raw)
+        : root.patterns.some((one) => one.test(relative))
+      if (hit) return true
+    }
+    return !owned
+  })
+}
+
+// La decisión completa, para que quien la consume sea una línea: ¿alcanza con correr sobre el árbol?
+// Recibe las líneas del delta tal como las devuelve `git status --porcelain`, ya sin lo ignorado.
+function staysInTree(roots, repoDir, deltaLines) {
+  const declared = Array.isArray(roots) ? roots : []
+  if (!declared.length) return false
+  return !reachesGate(declared, repoDir, deltaLines.map(fileOf))
+}
+
+// Sólo lo que otro módulo consume, por lo que dice el cierre de `cli/bench.js`. `toRegExp` se queda
+// adentro y no pierde nada: lo que hay que fijar de él son sus respuestas, y se ven igual preguntándole
+// a `reachesGate`.
+module.exports = { reachesGate, staysInTree }