@ingeniomaps/cauce 0.87.0 → 0.89.0

package/engine/cli/validate.js

@@ -0,0 +1,205 @@
+'use strict'
+
+// La puerta de un planning: qué está mal y qué conviene mirar, en un solo comando que falla.
+//
+// Vive aparte de los que leen el mismo estado porque hace lo contrario que ellos. `tree`, `context` y
+// `recurring` contestan una pregunta y salen en cero; éste junta errores y advertencias de dieciocho
+// módulos —estructura, contratos, reclamos, integraciones, ownership, onboarding— y decide si la
+// instancia puede seguir. De ahí que casi todo lo que el CLI de planning importa entre por acá y no por
+// allá: lo que valida necesita conocer a todos, y lo que informa sólo necesita el estado ya compuesto.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const P = require('../planning/parser')
+const B = require('../planning/business-rules')
+const PC = require('../planning/contracts')
+const SR = require('../planning/structure')
+const SZ = require('../planning/sizing')
+const RC = require('../planning/recurring')
+const IB = require('../planning/inbox')
+const CL = require('../planning/claims')
+const R = require('../core/repos')
+const AD = require('../planning/adoption')
+const AP = require('../hooks/approval')
+const I = require('../integrations/registry')
+const O = require('../core/ownership')
+const TR = require('../core/trails')
+const OB = require('../core/onboarding')
+const C = require('../config/validate')
+const CP = require('../config/paths')
+const AG = require('../agents/catalog')
+const RL = require('../automation/rules')
+const { fail, planningRoot, TODAY } = require('./io')
+
+function check(dir, cli) {
+  const root = planningRoot(dir)
+  const errors = []
+  const warnings = []
+  // El plan no está: `wip/` es local y gitignoreado, así que un clon nuevo no lo trae y eso no es un
+  // error. Ausente se lee como IDLE, que es lo que significa.
+  const required = ['BACKLOG.md', 'INBOX.md', 'HUMAN_ACTIONS.md', 'PROTOCOL.md']
+  // `DONE.md` se retiró: la evidencia vive en un archivo por tarea. Un `DONE.md` que quede en disco
+  // ya no lo lee nadie, y eso no se nota — las épicas dejan de poder cerrar y sus historias figuran
+  // sin evidencia, que es lo mismo que se vería si nunca se hubieran hecho.
+  // `WIP.md` se retiró por lo mismo que `DONE.md`: era uno solo y lo escribían todos los que corren sobre
+  // una instancia sidecar. Uno que quede en disco ya no lo lee nadie, y su plan a medias se pierde sin
+  // que nada lo diga.
+  if (fs.existsSync(path.join(root, 'WIP.md'))) {
+    errors.push('WIP.md ya no se lee: el plan de cada runner vive en `wip/<runner>.md`; movelo y borralo')
+  }
+  if (fs.existsSync(path.join(root, 'DONE.md'))) {
+    errors.push('DONE.md ya no se lee: pasá cada entrada a su propio `done/<slug>.md` y borralo')
+  }
+  for (const file of required) if (!fs.existsSync(path.join(root, file))) errors.push(`falta ${file}`)
+
+  const configPath = path.join(root, '..', 'ops.config.json')
+  let config = null
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, 'utf8')
+      config = JSON.parse(raw)
+      if (!raw.includes('{{')) {
+        errors.push(...C.validateOpsConfig(config))
+        warnings.push(...C.configWarnings(config))
+        if (Array.isArray(config.workspaceRoots)) {
+          for (const workspace of config.workspaceRoots) {
+            if (workspace && workspace.name && workspace.path
+              && !fs.existsSync(path.resolve(path.dirname(configPath), workspace.path))) {
+              errors.push(`ops.config.json: no existe la raíz ${workspace.name} (${workspace.path})`)
+            }
+          }
+        }
+        // Es la única parte de la configuración que le levanta el límite a un guard, y quien la escribió
+        // no es quien la lee dentro de seis meses: va como advertencia permanente, igual que un override.
+        // Y se muestra resuelta porque resuelta es como la compara el guard — un `~` escrito solo exenta
+        // la casa entera, y escrito no se nota.
+        for (const exempt of CP.writableOutsideRoots(path.dirname(configPath), config)) {
+          warnings.push(`ops.config.json: ${exempt.declared} está exenta del límite `
+            + `de raíces (${exempt.path})`)
+        }
+      }
+    } catch (error) {
+      errors.push(`ops.config.json: JSON inválido (${error.message})`)
+    }
+  } else {
+    warnings.push(`no existe ${path.relative(root, configPath)}`)
+  }
+
+  const epics = P.readEpics(root)
+  const milestones = P.readBacklog(root)
+  const done = P.readDone(root)
+  errors.push(...B.validate(path.join(root, 'business-rules')))
+  errors.push(...SR.validateRoadmapStructure(root))
+  errors.push(...SR.validateBacklogStructure(root))
+  errors.push(...SR.validateRules(root))
+  errors.push(...SR.validateAdr(root))
+  const backlog = milestones.flatMap((milestone) => milestone.tasks)
+  const roles = new Set(AG.list(path.resolve(root, '..')).map((role) => role.slug))
+  const wips = P.readWips(root)
+  const adopted = AD.read(root)
+  errors.push(...SZ.oversizedUnits({ epics, milestones }))
+  errors.push(...PC.validateState({
+    epics, milestones, done, wips, roles, humanActions: P.readHumanActions(root), adopted: new Set(adopted),
+  }))
+  warnings.push(...AD.report({ done, epics, adopted }))
+  warnings.push(...PC.doneCeremonyWarnings(done, new Set(adopted)))
+  // Antes de que el recorrido pague Build para descubrirlo en Verify. Cuesta un regex sobre la cola y
+  // corre en los cuatro carriles, incluidos los que saltean Ready (caso 140).
+  warnings.push(...PC.unverifiableAcceptance(milestones))
+  warnings.push(...R.coverageWarnings(path.resolve(root, '..'), done))
+  // Sin `RECURRING.md` no dice una palabra: una instancia que actualiza y no declara trabajo recurrente
+  // no tiene por qué enterarse de que el contrato existe. Vencida avisa y no frena — lo que frena vive
+  // en `HUMAN_ACTIONS.md`, y un aviso que salta siempre se termina apagando.
+  // Un reclamo que nombra una tarea que no existe bloquea la cola sin que nada lo explique, y uno viejo
+  // la bloquea para siempre. Lo primero es error; lo segundo avisa, porque abandonar no es un defecto.
+  const claims = CL.read(root)
+  errors.push(...CL.validate({ claims, milestones, done }))
+  // Si la rama de cada tarea tomada se movió, que es lo único barato que distingue una tarea larga de
+  // una abandonada. Sin repositorio resoluble el mapa queda vacío y el aviso vuelve a mirar sólo la
+  // fecha, que es lo que había antes: degrada, no rompe.
+  const activity = new Map()
+  for (const claim of claims.filter((one) => !done.set.has(one.slug))) {
+    const at = R.lastCommit(R.repoOf(path.join(root, '..'), claim.service), CL.branchOf(claim.slug))
+    if (at) activity.set(claim.slug, at)
+  }
+  warnings.push(...CL.warnings({ claims, done, today: TODAY(), activity }))
+  const recurring = RC.read(root)
+  errors.push(...RC.validate(recurring))
+  warnings.push(...RC.warnings(RC.status({ ...recurring, done, today: TODAY() })))
+  warnings.push(...IB.warnings(root, done, config))
+  warnings.push(...AD.sealWarnings(root))
+  warnings.push(...R.unrecordedHumanActions(path.resolve(root, '..'), P.readHumanActions(root)))
+  warnings.push(...AP.warnings(path.resolve(root, '..')))
+  warnings.push(...TR.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
+  // 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; `
+      + '`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 integration = I.validate(path.resolve(root, '..'))
+  errors.push(...integration.errors)
+  warnings.push(...integration.warnings)
+
+  warnings.push(...SR.competingSections(root))
+  // Sobrescribir una entrada de system/ es legítimo y esperado; lo que no puede pasar es que
+  // ocurra en silencio, porque esa entrada deja de recibir las mejoras del toolkit.
+  for (const override of O.overrides(path.resolve(root, '..'))) {
+    // Y con qué se queda el proyecto: un override sano redefine lo que reemplaza, y el que deja IDs
+    // afuera los retira sin decirlo. Nombrarlos es lo único que separa una decisión de un descuido.
+    const retired = override.collection === 'planning/rules'
+      ? SR.retiredByOverride(root, override.project)
+      : []
+    warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} `
+      + `(override explícito)${retired.length ? `; deja de regir ${retired.join(', ')}` : ''}`)
+  }
+  // Y lo que instaló cada runner, contra esas mismas reglas (caso 099).
+  warnings.push(...RL.staleLines(path.resolve(root, '..')))
+  // Y cuánto pesa lo que ese bloque carga, cuando ya se pasó del umbral. Es la contracara de la línea que
+  // `install` imprime al elegir: una instancia suma reglas de a una, cada una razonable, y el total no lo
+  // mira nadie hasta que una corrida sale cara.
+  warnings.push(...RL.heavyRules(path.resolve(root, '..')))
+  // Misma regla para los cargos, que es donde más caro sale: un fork se hace una vez y se olvida.
+  const FK = require('../agents/fork')
+  for (const entry of FK.drift(path.resolve(root, '..'))) warnings.push(FK.driftLine(entry))
+
+  warnings.push(...OB.missingSections(path.resolve(root, '..')))
+  warnings.push(...OB.orphanCredentials(path.resolve(root, '..')))
+
+  if (cli.has('--json')) {
+    console.log(JSON.stringify({
+      ok: !errors.length,
+      epics: epics.length,
+      queued: backlog.length,
+      done: done.entries.length,
+      wips: wips.map((one) => one.task),
+      errors,
+      warnings,
+    }))
+    if (errors.length) process.exit(1)
+    return
+  }
+
+  for (const warning of warnings) console.warn(`⚠ ${warning}`)
+  for (const error of errors) console.error(`✗ ${error}`)
+  if (errors.length) fail(`\n${errors.length} error(es), ${warnings.length} advertencia(s)`)
+  console.log(
+    `✓ planning válido: ${epics.length} épica(s), ${backlog.length} tarea(s) en cola, ` +
+      `${done.entries.length} terminada(s)`,
+  )
+}
+
+module.exports = { check }

package/engine/planning/contracts.js

@@ -155,6 +155,59 @@ function doneCeremonyWarnings(done, adopted = new Set()) {
   return warnings
 }
 
+// Lo que sólo existe después de Verify: el registro de la tarea, no su producto. `done/<slug>.md` lo
+// escribe Done, el commit lo escribe Commit y el reclamo se libera al cerrar, así que una aceptación que
+// pida verlos pide algo que en Verify todavía no puede estar.
+const POST_VERIFY = [
+  [/\bplanning\/done\b|\bdone\/|\bentrada de DONE\b/i, 'planning/done/'],
+  [/\bla evidencia\b|\bevidencia registrada\b/i, 'la evidencia'],
+  [/\bel commit\b|\bcommitead[oa]\b/i, 'el commit'],
+  [/\bel reclamo\b|\bclaims\//i, 'el reclamo'],
+]
+
+// La salida explícita, con la forma que el repositorio ya usa dos veces: `(sin partir: …)` para el umbral
+// de R17 y `n/a — razón` para `tests:` y `commit:`. Acá vale lo mismo que allá —«como lleva su razón
+// escrita se lee en el propio artefacto sin que nadie la cruce»— y por eso no se intenta adivinar si la
+// prosa excluye a Verify. Adivinarlo es lo que no se puede: la única aceptación real que nombra el commit
+// lo hace justamente para decir que no es condición de Verify, y cualquier lista de frases que la
+// reconociera enseñaría a escribir esa frase exacta para silenciar el aviso.
+const OUT_OF_VERIFY = /\(fuera de verify:\s*[^)]+\)/i
+
+// Una condición de aceptación que nombra el registro en vez del producto no se puede cumplir nunca: se
+// comprueba en Verify, que corre antes que Commit y que Done. El recorrido lo detecta —y hace bien—, pero
+// recién ahí: en la corrida que originó esto fueron 1,2 M de tokens y once agentes para terminar con el
+// trabajo hecho, sin commit y sin poder cerrar (caso 140).
+//
+// Avisa y no falla, por lo mismo que el aviso de HUMAN_ACTIONS resueltas sin commit —que nació del 121,
+// el mismo daño y el mismo tamaño—: el patrón es de texto y una aceptación legítima puede mencionar la
+// palabra sin depender de ella. Un aviso que salta siempre se termina apagando.
+//
+// Se juzga condición por condición y no la aceptación entera, que es el grano con el que Verify contrasta
+// —su `uncovered` enumera criterios—: las aceptaciones reales traen varias y marcar el párrafo completo
+// señala a las que están bien por vecindad. Y la marca se busca en la condición, no en la tarea, para que
+// excluir una no exima a las demás.
+//
+// Lo que corresponde casi siempre no es borrar la cláusula sino moverla: `tests:`, `qa:` y `commit:` de
+// DONE ya exigen ese registro (PROTOCOL), así que repetirlo en la aceptación no agrega garantía — agrega
+// un bloqueo. Cuando sí corresponde dejarla, se declara y pasa en silencio.
+function unverifiableAcceptance(milestones = []) {
+  const warnings = []
+  for (const milestone of milestones) {
+    for (const task of milestone.tasks || []) {
+      for (const condition of String(task.acceptance || '').split(';').map((one) => one.trim())) {
+        if (!condition || OUT_OF_VERIFY.test(condition)) continue
+        const nombra = POST_VERIFY.filter(([pattern]) => pattern.test(condition))
+        if (!nombra.length) continue
+        warnings.push(`BACKLOG ${task.slug}: una condición nombra ${nombra.map(([, what]) => what).join(', ')}`
+          + ', que existe después de Verify, así que no se puede comprobar cuando se la comprueba. Eso va '
+          + 'en tests:, qa: o commit: de su entrada de DONE, que ya lo exigen; si de verdad va acá, '
+          + 'declaralo con "(fuera de verify: <razón>)"')
+      }
+    }
+  }
+  return warnings
+}
+
 function duplicates(values) {
   return [...new Set(values.filter((value, index) => values.indexOf(value) !== index))]
 }
@@ -362,6 +415,7 @@ module.exports = {
   validateState,
   doneEntryErrors,
   doneCeremonyWarnings,
+  unverifiableAcceptance,
   validCommitTrace,
   validDecisionTrace,
   validTestTrace,

package/engine/planning/state.js

@@ -46,7 +46,9 @@ function currentTask({ milestones, done, wips = [], claims = [] }, blockers = []
   const wip = wips.find((one) => one.runner === P.wipName(runner)) || null
   const queue = milestones.flatMap((milestone) => milestone.tasks.map((task) => ({ ...task, hito: milestone.slug })))
   const mine = new Set(claims.filter((one) => runner && one.runner === runner).map((one) => one.slug))
-  const others = new Map(claims.filter((one) => !mine.has(one.slug)).map((one) => [one.slug, one.owner]))
+  // El reclamo entero y no sólo su dueño: quién lo tomó alcanza para decir que la tarea está ocupada, y
+  // no para decir cómo volver a ella. Eso lo dice el id desde el que se tomó, que vive en el mismo archivo.
+  const others = new Map(claims.filter((one) => !mine.has(one.slug)).map((one) => [one.slug, one]))
   if (wip) {
     const active = queue.find((task) => task.slug === wip.task)
       || {
@@ -69,15 +71,23 @@ function currentTask({ milestones, done, wips = [], claims = [] }, blockers = []
     claimed: Boolean(claimed),
     skipped: queue.filter((task) => !done.set.has(task.slug) && blocked.has(task.slug))
       .map((task) => task.slug),
-    taken: pending.filter((task) => others.has(task.slug))
-      .map((task) => ({ slug: task.slug, owner: others.get(task.slug) })),
+    // Un reclamo hecho desde otro id no siempre es de otro agente: puede ser el mismo, con el id resuelto
+    // distinto porque `runner()` lo deduce del árbol donde corre el proceso y en sidecar hay dos árboles
+    // plausibles. Ahí el plan existe, está escrito y queda invisible para quien lo escribió. Por eso viajan
+    // los dos: el id crudo, que es lo que se exporta para volver, y el plan que ese id dejó, si lo dejó.
+    taken: pending.filter((task) => others.has(task.slug)).map((task) => {
+      const claim = others.get(task.slug)
+      const plan = wips.find((one) => one.task === task.slug && one.runner === P.wipName(claim.runner))
+      return { slug: task.slug, owner: claim.owner, runner: claim.runner, wip: plan ? `${plan.runner}.md` : '' }
+    }),
     // Lo que espera a otra tarea, con cuál y quién la tiene: la tercera causa por la que una cola puede
     // no ofrecer nada, y `context` las distingue por la misma razón que distingue las otras dos.
     // El filtro garantiza que hay dependencias y que al menos una no está cerrada —sin eso la tarea
     // estaría lista y no acá—, así que buscarla no puede fallar y no lleva defensa.
     waiting: pending.filter((task) => !others.has(task.slug) && !ready(task)).map((task) => {
       const dep = task.depends.find((one) => !done.set.has(one))
-      return { slug: task.slug, dep, owner: others.get(dep) || (mine.has(dep) ? 'vos' : '') }
+      const otro = others.get(dep)
+      return { slug: task.slug, dep, owner: otro ? otro.owner : (mine.has(dep) ? 'vos' : '') }
     }),
   }
 }

package/package.json

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

package/template/planning/PROTOCOL.md

@@ -12,6 +12,11 @@ invariantes.
   puede heredar aceptación usando `(→ CN) (epic: NNN)` y declarar `(depende: slug, otro)`. Lane y cast son
   opcionales: sin ellos la tarea está sin clasificar, que es un estado y no un error. Una tarea con
   dependencias no se ofrece ni se toma hasta que todas estén en DONE.
+  Una condición se comprueba en Verify, que corre antes que Commit y que Done: la que nombre el commit, el
+  reclamo, `done/` o la evidencia registrada pide algo que todavía no existe cuando se la mira, y su lugar
+  son los campos `tests:`, `qa:` y `commit:` de DONE, que ya lo exigen. `check` lo avisa sobre la cola. Si
+  aun así corresponde dejarla ahí, se declara en la propia condición con `(fuera de verify: <razón>)` —la
+  misma salida explícita que `(sin partir: …)` y que `n/a — razón`— y deja de avisarse.
 - DONE: un archivo por tarea cerrada, `done/<slug>.md`, con su entrada `[x]` y los campos `acept:`,
   `fecha:` en AAAA-MM-DD, `done:`, `qa:`, `tests:`, `commit:` y `lane:`. `lane:` repite el carril con el
   que la tarea corrió —`express`, `directo`, `lite`, `full`— o `sin clasificar` si su línea no lo

package/template/planning/rules/README.md

@@ -26,3 +26,34 @@ lo hace—, y ahí queda exigida sin estar escrita en ningún lado. Por eso `che
 una regla nueva: si lo era, va acá al lado como `P1..Pn` y no se lleva nada puesto.
 
 Las convenciones específicas de lenguaje viven junto al servicio que usa ese lenguaje.
+
+## Una regla que sólo rige sobre una superficie
+
+Toda regla de este directorio se carga en el contexto de arranque de **cada** agente, y eso cuesta: sólo
+lo que trae Cauce son ~16 K tokens por agente, medido. Una regla propia de dos páginas que importa en una
+tarea de cada cien se lee cien veces.
+
+Una regla puede declarar a qué superficie pertenece, y entonces se **nombra** sin cargarse:
+
+```markdown
+---
+aplica: pagos
+---
+
+# Pagos
+
+## P3 — Conciliar antes de cerrar
+```
+
+Qué cambia: el bloque que `automation install` escribe la lista —`- ruta (aplica: pagos)`— en vez de
+importarla, así que pesa una línea y no su archivo entero. Sigue rigiendo igual: `ops context` la devuelve
+entre las reglas del proyecto, el recorrido se la nombra a cada agente que toca código, y quien trabaje
+sobre esa superficie la lee antes de planificar o construir.
+
+**Sin el campo, la regla se carga siempre.** Es el default a propósito: una regla que no se leyó no existe,
+así que apartarla del arranque es una decisión del proyecto y nunca algo que se deduzca. Por lo mismo el
+valor es libre y lo elige quien escribe la regla —`pagos`, `infraestructura`, `el front`—: lo que tiene que
+hacer es que quien lo lea sepa cuándo le toca.
+
+Conviene para lo que es de un dominio acotado —un proveedor, un stack, una integración— y no para lo que
+gobierna cómo se trabaja: esas se pagan y se cargan.