@ingeniomaps/cauce 0.90.0 → 0.91.0

package/CHANGELOG.md

@@ -14,6 +14,57 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
 diseño — eso vive en el commit y en el código.
 
+## [0.91.0] - 2026-09-15
+
+### Agregado
+
+- **`ops contract <ops-root> [--json]`: el contrato de tu proyecto sin pasarlo por un modelo.** Devuelve lo
+  que un recorrido necesita 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/`—, derivado de `ops.config.json`,
+  `AGENTS.md`, `organization/workspace.md` y `planning/PROTOCOL.md`.
+
+  Los diez campos salen de parsear, así que el comando no inventa nada y cuesta cero tokens. `autobuild` los
+  derivaba con un agente que leía esos cuatro archivos y los transcribía; el comando existe para que deje de
+  hacerlo, aunque el recorrido todavía no lo use.
+
+  **Falla en vez de contestar a medias.** Si falta uno de los cuatro archivos, o si `AGENTS.md` o
+  `PROTOCOL.md` perdieron la sección de la que sale el contrato, se niega nombrando cuál y manda a correr
+  `ops upgrade`, que es quien los repone: entregar límites vacíos es peor que parar, porque un límite que no
+  llega se lee igual que uno que no existe. Que `organization/workspace.md` no declare excepciones **no** es
+  un error: es tuyo y puede no tenerlas.
+
+### Corregido
+
+- **La protección que evita que un gate te borre el `node_modules` no estaba puesta.** `verify` corre los
+  gates sobre una copia del índice con el `node_modules` enlazado a tu proyecto, y le pedía a pnpm que no
+  sincronizara dependencias antes de correr el script. Se lo pedía con un nombre que pnpm ignora: sus
+  ajustes se leen del entorno con el prefijo `pnpm_config_`, no con el de npm. La petición viajaba y se
+  descartaba en silencio desde 0.75.0, que es cuando entró.
+
+  Con pnpm 11, donde esa comprobación viene encendida, se nota al commitear un cambio de `pnpm-lock.yaml`:
+  pnpm decide reinstalar, la reinstalación **empieza borrando** el directorio de módulos —el tuyo, por el
+  enlace— y sin TTY aborta con `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`. Los gates vuelven en poco más
+  de un segundo, así que se leen como una suite en rojo que no lo es.
+
+  Si te está pasando, alcanza con actualizar. Lo que **no** corresponde, aunque el bloqueo lo sugiera, es
+  aprobar las rutas o `OPS_SKIP_VERIFY=1` —las dos commitean sin haber corrido el gate— ni `CI=true`, que
+  desarma justamente la confirmación con la que pnpm frena antes de purgar.
+
+- **`plan-first` decía que no tenías plan cuando lo que pasaba es que no veía el tuyo.** El guard busca el
+  WIP de tu id, y ese id sale del árbol donde corre el proceso mientras no exportes `CAUCE_RUNNER`. Con la
+  instancia al lado de dos repositorios, el mismo cambio se frenaba o pasaba según el directorio desde el
+  que saliera la llamada — y el bloqueo decía «WIP está en IDLE» con el plan escrito y a la vista, así que
+  mandaba a escribir de nuevo algo que ya existía.
+
+  Ahora distingue las dos causas: si hay un plan bajo otro id, lo nombra con su tarea y te manda a volver a
+  ese id —`ops runners <planning>` los lista— o a montar el tuyo con `ops worktree <planning> <tarea>`. Y
+  **deja de ofrecerte aprobar la ruta**, porque con un plan a la vista eso escribe por vos que el cambio no
+  es trabajo de ninguna tarea, que es falso y queda en el registro.
+
+  Lo que no cambia: el plan de otro runner sigue sin autorizarte a escribir. Si van a trabajar en paralelo,
+  cada agente necesita su árbol —`git worktree`, que es lo que `ops worktree` prepara—, y ahí el problema no
+  existe porque no comparten archivos.
+
 ## [0.90.0] - 2026-09-15
 
 ### Corregido

package/engine/cli/args.js

@@ -20,6 +20,7 @@ const FLAGS = {
   check: ['--json'],
   tree: ['--json', '--no-color'],
   context: ['--json', '--hito'],
+  contract: ['--json'],
   recurring: ['--json', '--promote'],
   claim: ['--json'],
   runners: ['--json'],

package/engine/cli/contract.js

@@ -0,0 +1,127 @@
+'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.
+function limits(text) {
+  return 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))
+}
+
+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 }

package/engine/cli/ops.js

@@ -9,6 +9,7 @@ const { FLAGS, parse } = require('./args')
 const { fail } = require('./io')
 const IN = require('./instance')
 const PL = require('./planning')
+const CT = require('./contract')
 const VA = require('./validate')
 const AR = require('./archive')
 const CLM = require('./claims')
@@ -149,6 +150,7 @@ 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 recurring <planning-dir> [--promote <qué>] [--json]
   ops runners <planning-dir> [--json]
   ops claim <planning-dir> <tarea>
@@ -208,6 +210,7 @@ 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 === '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/hooks/files.js

@@ -14,7 +14,7 @@ const {
 const AP = require('./approval')
 const CHAT = require('./chat')
 const { selfApproval } = require('./self-approval')
-const { readWip } = require('../planning/parser')
+const { readWip, readWips } = require('../planning/parser')
 const { runner } = require('../planning/claims')
 const { hasTasks } = require('../planning/state')
 const { TEMPLATE_PREFIXES } = require('../core/ownership')
@@ -235,14 +235,33 @@ function planFirst(input) {
   // Que el guard quede inerte lo dice `automation check`, porque una condición invisible es peor que
   // no tenerla.
   if (!hasTasks(planning)) return
+  // No tener plan y no ver el propio piden cosas opuestas: escribirlo, o volver al id desde el que ya se
+  // escribió. `runner()` sale del árbol donde corre el proceso, así que con una instancia al lado de dos
+  // repositorios el mismo cambio cae de un lado o del otro según el directorio, y el mensaje mandaba a
+  // escribir un plan que estaba a la vista (caso 152).
+  //
+  // Se lista recién acá, después de las dos salidas de arriba: quien tiene su plan sale por la primera y
+  // no paga esta lectura, que es la misma razón por la que `hasTasks` se pregunta donde se pregunta.
+  const ajenos = readWips(planning).filter((one) => one.complete + one.pending > 0)
   const estado = wip ? `WIP tiene la tarea ${wip.task} y ningún paso` : 'WIP está en IDLE'
-  const why = `${estado}, así que el plan todavía no está escrito.\n`
-    + 'Escribí en tu planning/wip/<runner>.md la tarea y su plan aprobado —pasos numerados, cada uno con un estado '
-    + 'verificable— y volvé al cambio. Si esto no es trabajo de una tarea, aprobá la ruta.\n'
+  const why = ajenos.length
+    ? `hay plan escrito, pero bajo otro id: ${ajenos.map((one) => `${one.runner} (${one.task})`).join(', ')}.\n`
+      + 'Si ese plan es tuyo, volvé a su id con `export CAUCE_RUNNER=<id>` —`ops runners <planning>` los lista '
+      + 'con su tarea y su avance— y repetí el cambio. Si vas a trabajar en paralelo, montá tu propio árbol '
+      + 'con `ops worktree <planning> <tarea>`, que te devuelve el id hecho.\n'
+    : `${estado}, así que el plan todavía no está escrito.\n`
+      + 'Escribí en tu planning/wip/<runner>.md la tarea y su plan aprobado —pasos numerados, cada uno con '
+      + 'un estado verificable— y volvé al cambio. Si esto no es trabajo de una tarea, aprobá la ruta.\n'
   for (const raw of filesOf(input)) {
     if (!isProduct(root, path.resolve(cwdOf(input), raw))) continue
     if (approved(input, raw)) continue
-    block(`${raw} cambia el producto sin plan. ${why}${AP.HOW('OPS_PLAN_FIRST_OVERRIDE', [raw], input)}`)
+    // Con un plan a la vista no se ofrece ninguna de las dos salidas: aprobar la ruta escribe «esto no es
+    // trabajo de una tarea», que ahí es falso, y anunciar la variable ofrece el permiso más ancho cuando
+    // la acción correcta es angosta y concreta —el mismo criterio con que `HOW` decide no nombrarla—.
+    const how = ajenos.length
+      ? AP.HOW(null, [], input, [])
+      : AP.HOW('OPS_PLAN_FIRST_OVERRIDE', [raw], input)
+    block(`${raw} cambia el producto sin plan. ${why}${how}`)
   }
 }
 

package/engine/hooks/shell.js

@@ -488,11 +488,17 @@ function commitTree(dir) {
   // el lockfile de la copia y reinstala, lo que **empieza borrando** el `node_modules` del proyecto.
   //
   // Lo que se apaga es esa comprobación previa, que es el motivo por el que quiere tocar nada.
-  // `verify-deps-before-run` la gobierna y tiene tres valores: `install` reinstala solo —el que trae
-  // pnpm 11 y el que hace el daño—, `error` se niega y frena el gate cuando el lockfile de la copia
-  // difiere de lo instalado, que es justo lo que pasa al commitear un cambio de lockfile por partes, y
-  // `false` corre el script sin mirar. La copia no tiene que sincronizar nada: tiene que medir el
-  // código.
+  // `verify-deps-before-run` la gobierna y tiene cinco valores —`install`, `warn`, `prompt`, `error` y
+  // `false`—. El que hace el daño es `install`, que reinstala solo y es el default desde pnpm 11. `error`
+  // tampoco serviría: frena el gate cuando el lockfile de la copia difiere de lo instalado, que es justo
+  // lo que pasa al commitear un cambio de lockfile por partes. La copia no tiene que sincronizar nada:
+  // tiene que medir el código.
+  //
+  // El prefijo es `pnpm_config_` y no `npm_config_`, y esa sola palabra es la diferencia entre apagar la
+  // comprobación y no apagar nada: pnpm lee sus ajustes del entorno con su propio prefijo, así que con el
+  // de npm la variable llega igual y se ignora en silencio. Acá estuvo `npm_config_` desde el arreglo del
+  // 070 y no surtió efecto nunca (caso 151), con lo cual la protección que ese arreglo creyó poner no
+  // estuvo puesta. Medido sobre pnpm 10.30.2 y 11.20.0, iguales las dos.
   //
   // Acá estuvo `CI: 'true'` y fue una regresión (caso 070). Resolvía el síntoma del 068 —pnpm dejaba de
   // preguntar antes de purgar— desarmando la confirmación en vez de quitarle el motivo, y esa
@@ -502,7 +508,7 @@ function commitTree(dir) {
   //
   // La regla que queda: no se desarma la confirmación de una herramienta, se le quita el motivo de
   // preguntar. Una confirmación que estorba casi siempre está cuidando algo.
-  return { root: temp, temp, env: { npm_config_verify_deps_before_run: 'false' } }
+  return { root: temp, temp, env: { pnpm_config_verify_deps_before_run: 'false' } }
 }
 
 function verify(input) {

package/package.json

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