@ingeniomaps/cauce 0.95.0 → 0.97.0

package/engine/cli/wiring.js

@@ -14,7 +14,7 @@ const SC = require('../core/scan')
 const OB = require('../core/onboarding')
 const IN = require('./instance')
 const ST = require('../planning/state')
-const { fail, opsRoot } = require('./io')
+const { fail, opsRoot, USAGE, REFUSED } = require('./io')
 
 // Cuántos servicios se listan en pantalla antes de recortar. El resto sigue en `--json`, que es lo que
 // consume el recorrido de arranque: recortar la lista es para leerla, no para acotar lo que se sabe.
@@ -45,7 +45,7 @@ const INTEGRATION = {
         && fs.existsSync(path.join(root, 'integrations', provider))
       if (!fromCauce && !own) {
         fail(`Cauce no trae un adaptador para ${provider}. Uno propio vive en integrations/${provider}/ y se `
-          + `registra en integrations/config.json con "adapter": "./adapter.js"; con eso, enable lo conecta.`, 2)
+          + `registra en integrations/config.json con "adapter": "./adapter.js"; con eso, enable lo conecta.`, USAGE)
       }
       // Habilitar no es inicializar: repone lo que falte y conserva lo que ya esté. Una instancia que
       // trae el andamiaje de una versión anterior —o que ya tiene snapshots— sólo quiere el interruptor.
@@ -86,7 +86,7 @@ const INTEGRATION = {
       const result = I.validate(root, provider || '')
       for (const warning of result.warnings) console.warn(`⚠ ${warning}`)
       for (const error of result.errors) console.error(`✗ ${error}`)
-      if (result.errors.length) fail(`${result.errors.length} error(es) de integración`)
+      if (result.errors.length) fail(`${result.errors.length} error(es) de integración`, REFUSED)
       console.log(`✓ integraciones válidas${provider ? `: ${provider}` : ''}`)
     },
   },
@@ -203,14 +203,14 @@ function onboard(rootArg, cli, runner = '') {
 function providerRegistry(root) {
   const file = path.join(root, 'integrations', 'config.json')
   try { return { file, config: JSON.parse(fs.readFileSync(file, 'utf8')) } } catch (error) {
-    return fail(`integrations/config.json ilegible: ${error.message}`)
+    return fail(`integrations/config.json ilegible: ${error.message}`, USAGE)
   }
 }
 
 function switchProvider(root, provider, enabled) {
   const { file, config } = providerRegistry(root)
   if (!config.providers || !config.providers[provider]) {
-    fail(`${provider} no está en integrations/config.json.`)
+    fail(`${provider} no está en integrations/config.json.`, USAGE)
   }
   config.providers[provider].enabled = enabled
   F.atomicWriteJson(file, config)
@@ -218,8 +218,8 @@ function switchProvider(root, provider, enabled) {
 
 async function integration(action, rootArg, provider, key, cli) {
   const step = INTEGRATION[action]
-  if (!step) fail(`Acción de integración desconocida: ${action || '(vacía)'}`, 2)
-  if (step.missing && (!provider || (step.needsKey && !key))) fail(step.missing, 2)
+  if (!step) fail(`Acción de integración desconocida: ${action || '(vacía)'}`, USAGE)
+  if (step.missing && (!provider || (step.needsKey && !key))) fail(step.missing, USAGE)
   await step.run(path.resolve(rootArg || '.'), provider, key, cli)
 }
 
@@ -245,7 +245,7 @@ function automation(action, rootArg, runnerName, cli) {
   if (action === 'check') {
     const errors = A.check(root)
     for (const error of errors) console.error(`✗ ${error}`)
-    if (errors.length) fail(`${errors.length} error(es) de automatización`)
+    if (errors.length) fail(`${errors.length} error(es) de automatización`, REFUSED)
     console.log(
       `✓ automatización válida: ${A.GUARD_NAMES.length} guards, ${A.RUNNER_NAMES.length} adaptadores`,
     )
@@ -260,22 +260,22 @@ function automation(action, rootArg, runnerName, cli) {
   }
   if (action === 'doctor') {
     let result
-    try { result = A.doctor(root, runnerName) } catch (error) { fail(error.message, 2) }
+    try { result = A.doctor(root, runnerName) } catch (error) { fail(error.message, USAGE) }
     if (result.errors.length) {
-      fail(`${runnerName}: ${result.errors.length} error(es), ${result.warnings.length} advertencia(s)`)
+      fail(`${runnerName}: ${result.errors.length} error(es), ${result.warnings.length} advertencia(s)`, REFUSED)
     }
     console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
     return
   }
   if (action === 'uninstall') {
-    try { A.uninstall(root, runnerName, console) } catch (error) { fail(error.message, 2) }
+    try { A.uninstall(root, runnerName, console) } catch (error) { fail(error.message, USAGE) }
     console.log('  la instancia sigue en pie: borrar la carpeta ops es una decisión aparte.')
     return
   }
   if (action === 'install') {
     let runner
     const force = cli.has('--force')
-    try { runner = A.install(root, runnerName, console, { force }) } catch (error) { fail(error.message, 2) }
+    try { runner = A.install(root, runnerName, console, { force }) } catch (error) { fail(error.message, USAGE) }
     if (runnerName === 'codex') {
       console.log('  Codex deja los hooks nuevos sin correr hasta que los confíes: abrí una sesión')
       console.log('  y usá /hooks para revisarlos y marcarlos como confiables.')
@@ -284,20 +284,20 @@ function automation(action, rootArg, runnerName, cli) {
       console.log(`  ${runnerName} no expone hooks nativos; aplica guards como prechecks.`)
     }
     const result = A.doctor(root, runnerName)
-    if (result.errors.length) fail(`${runnerName}: instalación incompleta`)
+    if (result.errors.length) fail(`${runnerName}: instalación incompleta`, REFUSED)
     console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
     return
   }
-  fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, 2)
+  fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, USAGE)
 }
 
 function secrets(action, rootArg) {
-  if (action !== 'check') fail(`Acción de secretos desconocida: ${action || '(vacía)'}`, 2)
+  if (action !== 'check') fail(`Acción de secretos desconocida: ${action || '(vacía)'}`, USAGE)
   const result = SE.check(opsRoot(rootArg))
   if (!result.declared) return console.log(`Sin ${SE.DECLARATION}: no hay contrato de secretos que comprobar.`)
   for (const warning of result.warnings) console.log(`⚠ ${warning}`)
   for (const error of result.errors) console.error(`✗ ${error}`)
-  if (result.errors.length) fail(`${result.errors.length} error(es) en el contrato de secretos`)
+  if (result.errors.length) fail(`${result.errors.length} error(es) en el contrato de secretos`, REFUSED)
   console.log(`✓ contrato de secretos: ${result.current} servicio(s) al día`)
 }
 

package/engine/cli/worktree.js

@@ -15,7 +15,7 @@ const ST = require('../planning/state')
 const CL = require('../planning/claims')
 const R = require('../core/repos')
 const O = require('../core/ownership')
-const { fail, planningRoot } = require('./io')
+const { fail, planningRoot, USAGE, REFUSED } = require('./io')
 
 const git = (cwd, ...args) => spawnSync('git', args, { cwd, encoding: 'utf8' })
 
@@ -34,38 +34,38 @@ function existing(repo, branch) {
 
 function worktree(dir, slug, cli) {
   const root = planningRoot(dir)
-  if (!slug) return fail('Falta el slug. `ops worktree <planning-dir> <tarea>`', 2)
+  if (!slug) return fail('Falta el slug. `ops worktree <planning-dir> <tarea>`', USAGE)
   const state = ST.snapshot(root)
   const task = state.milestones.flatMap((milestone) => milestone.tasks).find((one) => one.slug === slug)
-  if (!task) return fail(`${slug} no está en BACKLOG: sólo se prepara trabajo ya promovido.`, 2)
+  if (!task) return fail(`${slug} no está en BACKLOG: sólo se prepara trabajo ya promovido.`, USAGE)
 
   // No reserva —eso es `claim`— pero se niega a montar sobre lo de otro: preparar un árbol para una
   // tarea ajena es trabajo que se va a tirar, y el aviso cuesta menos que descubrirlo después.
   const taken = state.claims.find((one) => one.slug === slug)
   if (taken && taken.runner !== CL.runner()) {
-    return fail(`${slug} la tomó ${taken.owner}; preparar un árbol para su tarea no ayuda a nadie.`)
+    return fail(`${slug} la tomó ${taken.owner}; preparar un árbol para su tarea no ayuda a nadie.`, REFUSED)
   }
 
   const candidatos = R.reposFor(path.join(root, '..'), task.service)
   if (candidatos.length > 1) {
     return fail(`${task.service || '.'} existe en más de un repositorio (${candidatos.join(', ')}), así que `
-      + 'no puedo saber cuál. Escribí un `service:` que sólo exista en uno.', 2)
+      + 'no puedo saber cuál. Escribí un `service:` que sólo exista en uno.', USAGE)
   }
   const repo = candidatos[0]
   if (!repo) {
     return fail(`no encontré el repositorio de ${task.service || '(sin service)'}: revisá workspaceRoots `
-      + 'en ops.config.json y que la ruta del servicio exista.', 2)
+      + 'en ops.config.json y que la ruta del servicio exista.', USAGE)
   }
 
   const branch = CL.branchOf(slug)
   const already = existing(repo, branch)
   const target = already || path.join(path.dirname(repo), `${path.basename(repo)}-${slug}`)
   if (!already) {
-    if (fs.existsSync(target)) return fail(`${target} ya existe y no es un árbol de esta rama.`)
+    if (fs.existsSync(target)) return fail(`${target} ya existe y no es un árbol de esta rama.`, REFUSED)
     const hasBranch = git(repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`).status === 0
     const args = hasBranch ? ['worktree', 'add', target, branch] : ['worktree', 'add', '-b', branch, target]
     const added = git(repo, ...args)
-    if (added.status !== 0) return fail(`git worktree add falló: ${(added.stderr || '').trim()}`)
+    if (added.status !== 0) return fail(`git worktree add falló: ${(added.stderr || '').trim()}`, REFUSED)
   }
 
   if (cli.has('--json')) {

package/engine/core/ownership.js

@@ -164,9 +164,16 @@ function engineAt(root, relative = '') {
 // de copiarse. Se reconocen por contener `system/`, que es el espacio del toolkit y no algo que un
 // proyecto deba crear. Una sola implementación para las dos, o divergen.
 function packageDir(root, name) {
+  // La raíz declarada va también acá, y no sólo en `packagePath`. Las dos contestan dónde está el paquete
+  // sobre la misma instancia y desde el 158 contestaban distinto: en el layout documentado —`npm install`
+  // en la carpeta de la empresa y la instancia adentro— el motor se resolvía y el catálogo no, así que
+  // `check` pasaba en verde y `agents list` devolvía una lista vacía con exit 0, indistinguible de «esta
+  // instancia no tiene cargos». `evaluate` era peor: culpaba a un `SKILL.md` que falta (caso 171).
+  const above = declaredRoot(root)
   const candidates = [
     path.join(root, 'node_modules', '@ingeniomaps', 'cauce', name),
     path.join(root, name),
+    ...(above ? [path.join(above, 'node_modules', '@ingeniomaps', 'cauce', name)] : []),
   ]
   return candidates.find((dir) => fs.existsSync(path.join(dir, 'system'))
     || fs.existsSync(path.join(dir, 'roles', 'system'))) || ''

package/engine/hooks/shell.js

@@ -45,6 +45,20 @@ const COMANDO = String.raw`$|[;&|)'"\`]`
 // de frenar trabajo legítimo nombraba una violación que no estaba.
 const MISMO = String.raw`[^;&|\n]`
 
+// Si algún remoto alcanza al commit que está en HEAD. Lectura local e inocua: `branch -r` mira lo que ya
+// está en `refs/remotes/`, no habla con ningún servidor. Un `fetch` que nadie corrió deja la respuesta
+// desactualizada hacia el lado seguro — cree que no está publicado algo que sí lo está—, y por eso esto
+// acota un bloqueo y no autoriza nada: lo que decide publicar sigue siendo `push`, que mira otra cosa.
+//
+// Sin git, sin repositorio o con el comando fallando, la respuesta es **sí**: cerrado por defecto (R27).
+// No saber si algo se publicó no es lo mismo que saber que no.
+function publishedHead(input) {
+  const cwd = (input && input.cwd) || process.cwd()
+  const result = spawnSync('git', ['branch', '-r', '--contains', 'HEAD'], { cwd, encoding: 'utf8' })
+  if (result.status !== 0) return true
+  return Boolean(result.stdout.trim())
+}
+
 // Un mensaje de commit es dato, no código. `git commit -m "fix: bloquear git push --force"` disparaba
 // el guard de publicación, y lo mismo `rm -rf /` nombrado en una explicación; con el heredoc que se usa
 // para un mensaje largo, el cuerpo entero entra en el comando, así que la línea que arregla esto no se
@@ -80,13 +94,22 @@ function destructive(input) {
   publish(input, command)
   const rules = [
     [/\bgit\s+reset\s+--hard\b/, "'git reset --hard' destruye cambios locales.", true],
-    // R8 lo prohíbe sin excepción configurable y ningún guard lo miraba: `grep -rn amend engine/hooks/`
-    // no devolvía una línea. Se bloquea por política y no por daño —un `--amend` sobre algo que nadie vio
-    // no rompe nada—, así que el mensaje manda a lo que sí corresponde: otro commit.
-    [
+    // Lo que R8 protege es la historia que **otro ya leyó**, y el motor ya hace esa distinción para el
+    // push: publicar se autoriza, reescribir lo publicado no. Acá se hace la misma, mirando si algún
+    // remoto alcanza a HEAD.
+    //
+    // Antes se bloqueaba siempre, «por política y no por daño», y eso no impedía el resultado sino el
+    // comando que lo nombra: `git reset --soft HEAD~1` y volver a commitear produce exactamente lo mismo,
+    // no lo frena ningún guard y no deja constancia de nada. Una regla que se cumple mejor esquivándola se
+    // termina esquivando siempre (caso 178).
+    //
+    // Y no lleva salida por chat ni publicado ni sin publicar: sin publicar no la necesita, y publicado es
+    // la misma reescritura que el force-push, que tampoco la tiene.
+    ...(publishedHead(input) ? [[
       new RegExp(String.raw`\bgit\s+commit\b${MISMO}*\s--amend\b`),
-      "'git commit --amend' reescribe un commit ya creado. R8 pide uno nuevo en su lugar.",
-    ],
+      "'git commit --amend' sobre un commit ya publicado reescribe historia que otro leyó. R8 lo "
+        + 'prohíbe: hacé otro commit encima.',
+    ]] : []),
     [/\bgit\s+clean\s+-[^\s]*f/, "'git clean -f' borra archivos sin seguimiento.", true],
     // `git checkout -- .` destruye lo mismo que `reset --hard` y sin recuperación, pero se escribe como
     // una limpieza. Se bloquea sólo la forma ancha —`.`, `*`, `:/`, o sin ruta—: revertir un archivo

package/engine/planning/contracts.js

@@ -383,6 +383,25 @@ function validateState({
     if (!row.valid) {
       errors.push(`HUMAN_ACTIONS ${row.task}: estado "${row.state}" fuera de `
         + `${P.HUMAN_ACTION_STATES.join(' | ')}; mientras no se entienda, la tarea queda bloqueada`)
+      continue
+    }
+    // La primera columna es a la vez lo que una persona lee y la clave con la que el motor bloquea:
+    // la selección de tarea (`state.js`) arma su conjunto de bloqueadas con ella tal cual. Esa doble
+    // función es libre a propósito —el molde manda
+    // nombrar la épica o el recorrido cuando la tarea todavía no existe— así que lo que no se puede
+    // recortar es la libertad, y lo que sí se puede es la forma intermedia: la celda que **menciona** una
+    // tarea de la cola sin ser su slug.
+    //
+    // Es la peor de las tres porque promete un bloqueo que no ocurre, y nada lo dice: la fila se escribe
+    // sin error, sale en `ops context` bajo HUMAN como si estuviera registrada, y la tarea se sigue
+    // ofreciendo. `**slug: de qué se trata**` es la que sale natural, porque esta tabla la lee una
+    // persona. Sin esto la ausencia no deja rastro, que es la forma de R15 aplicada a un mecanismo.
+    if (backlogSlugs.has(row.task)) continue
+    const casi = [...backlogSlugs].find((slug) => new RegExp(`\\b${slug}\\b`).test(row.task))
+    if (casi) {
+      errors.push(`HUMAN_ACTIONS: la fila "${row.task}" nombra a ${casi} y no bloquea nada, porque el `
+        + `motor bloquea por la primera columna exacta. Dejá "${casi}" sola ahí y contá el resto en la `
+        + 'acción, o nombrá la épica o el recorrido si lo que se frena no es esa tarea')
     }
   }
 

package/engine/planning/parser.js

@@ -176,6 +176,10 @@ function readCast(rest) {
 // devolvía `MAX` con `check` en verde, que es la forma cara del error —la tarea se lee completa y no
 // lo está—. Cierra el `_` que markdown cerraría: el que no está entre caracteres de palabra.
 const ACCEPTANCE = /_Aceptaci[oó]n:\s*(.*?\S)_(?![A-Za-z0-9])/i
+// Los paréntesis del contrato de una línea de tarea. Se enumeran por su clave y no como «cualquier
+// paréntesis» para no llevarse puesta una aclaración de la prosa: la descripción usa paréntesis igual
+// que cualquier texto, y el criterio `(→ C1)` va acá porque `criteria` ya lo extrae.
+const MARKERS = /\((?:→|->|criterios?\s|epic:|service:|cast:|depende:|sin partir:)[^)]*\)/gi
 
 // Cuántas condiciones tiene una aceptación escrita en prosa. Estuvo mucho tiempo sin contarse con una
 // razón buena —contar condiciones en una frase es una lectura, y un número inventado es peor que
@@ -207,6 +211,19 @@ function taskFromLine(line) {
     epic: ((rest.match(/\(epic:\s*(\d{3})\)/) || [])[1] || ''),
     service: ((rest.match(/\(service:\s*([^)]+)\)/) || [])[1] || '').trim(),
     acceptance,
+    // Lo que la aceptación no puede decir y alguien ya decidió: dónde vive un símbolo, qué queda fuera de
+    // alcance, con qué se produce la evidencia. Por contrato la aceptación describe estado observable del
+    // producto, así que una decisión de diseño no cabe ahí — y hasta acá tampoco salía del BACKLOG: el
+    // texto vivía en `rest` y se descartaba.
+    //
+    // Sin ella el que planifica vuelve a decidir lo ya decidido, y decide distinto. La crítica **sí** abre
+    // el BACKLOG y bloquea el plan citando la línea palabra por palabra: una compuerta juzga contra un
+    // texto que la otra no recibió. Dos corridas reales se pagaron enteras para descubrirlo, 1,10 M y
+    // 815 k tokens, la segunda con sus cuatro objeciones diciendo lo mismo (caso 177).
+    //
+    // Se recorta la aceptación y los marcadores del contrato porque cada uno ya tiene su campo: repetirlos
+    // acá los pone dos veces en el prompt de cada fase, que es lo que R16 cobra una vez por etapa.
+    description: rest.replace(ACCEPTANCE, '').replace(MARKERS, '').replace(/\s+/g, ' ').trim(),
     conditions: acceptanceConditions(acceptance),
     criteria: criteriaRefs(rest),
     // De qué otras tareas depende. El orden del BACKLOG alcanzaba mientras hubiera un runner: con dos,
@@ -388,6 +405,23 @@ function readWip(dir, runner) {
   return parseWip(read(path.join(dir, 'wip', `${name}.md`)), name)
 }
 
+// Si el checkpoint de hito sigue frenando, leído del archivo y no de que el archivo esté. Es la misma
+// forma que el WIP de acá arriba —`status: IDLE` es un estado escrito— y la razón es R28: un centinela
+// cuya única información es existir obliga a que el borrado sea parte de la resolución, y esa es una
+// convención que alguien va a olvidar. Cuando se olvida, quien revisa lee que el hito ya se revisó
+// mientras el mecanismo sigue leyendo que el archivo está, y la corrida siguiente muere en la puerta de
+// entrada habiendo cargado el estado entero.
+//
+// Cerrado por defecto (R27): frena salvo que diga `resuelta`. Un archivo de una instancia anterior no
+// trae `status`, y abrirlo por eso destrabaría en silencio al actualizar, que es la quita escrita como
+// agregado que R9 nombra. El vocabulario es el mismo de `HUMAN_ACTIONS.md` a propósito: es el mismo acto
+// —una persona contesta— y dos palabras para eso serían dos convenciones que aprender.
+function checkpointHolds(dir) {
+  const text = read(path.join(dir, 'AWAITING_REVIEW.md'))
+  if (!text) return false
+  return !/^status:\s*resuelta\b/mi.test(text)
+}
+
 // Todos los que hay. Lo pregunta `check`, que juzga si cada plan apunta a una tarea que existe, y `tree`,
 // que muestra qué está en vuelo: las dos son preguntas sobre la instancia y no sobre quien pregunta.
 function readWips(dir) {
@@ -436,6 +470,7 @@ module.exports = {
   EPIC_STATES, HUMAN_ACTION_STATES, LANES, MILESTONE_HEADING, STOP_REASONS,
   TASK_LINE, TASK_LINE_ANY_LANE,
   read, section, withoutComments, frontmatter, readEpics, readBacklog, readDone, readWip, readWips, wipName,
+  checkpointHolds,
   acceptanceConditions, tableRows, taskFromLine,
   readInbox, inboxHeads, readHumanActions,
 }

package/package.json

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

package/template/planning/rules/system/commits.md

@@ -3,7 +3,13 @@
 ## R8 — Un commit por naturaleza
 
 Stagear rutas explícitas, revisar el diff staged y crear un Conventional Commit en inglés. No usar
-`git add .`, `git add -A`, amend, force ni trailers de IA.
+`git add .`, `git add -A`, force ni trailers de IA.
+
+**Y no reescribir historia que otro ya leyó.** Lo que se protege es eso, no el comando: un `--amend`
+sobre un commit publicado es la misma reescritura que un force-push y se frena igual; sobre uno que no
+salió de tu máquina es la corrección, y prohibirlo no impide el resultado —`git reset --soft HEAD~1` y
+volver a commitear produce exactamente lo mismo— sino el comando que lo nombra. Una regla que se cumple
+mejor esquivándola se termina esquivando siempre.
 
 Dónde corta un commit lo decide la naturaleza del diff, no su tamaño ni un conteo. Una tarea suele
 tener una sola, y por eso un commit por tarea es lo habitual; cuando tiene dos, se hacen dos. Un
@@ -90,7 +96,8 @@ Push, PR, merge, tags, deploy y rollback requieren la autorización configurada
 De esos seis, el motor comprueba uno: el push, contra `runner.allowPush` —que no llega a la rama viva
 sin `runner.pushToLiveBranches`, ni a un subagente— o contra la orden que la persona da en el chat
 nombrando el remoto y la rama. Reescribir historia publicada
-no entra en esa autorización y se frena siempre, igual que `--amend`. Los otros cinco no tienen una
+no entra en esa autorización y se frena siempre — también cuando la reescritura es un `--amend`, que el
+guard distingue mirando si algún remoto alcanza al commit. Los otros cinco no tienen una
 forma reconocible en un comando —un deploy es `kubectl`, `terraform`, un script o un botón— y los
 sostiene esta regla y el review, no un guard.