@ingeniomaps/cauce 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -8,6 +8,26 @@ esa operación sea confiable en vez de sólo cómoda: acá se lee qué cambió a
 un cambio en el protocolo, en las reglas del sistema o en un guard es visible para el usuario y sube
 minor aunque no toque una sola línea de código.
 
+## [0.5.1] - 2026-08-15
+
+### Agregado
+
+- **Codex recibe su `AGENTS.md`.** Era el único runner sin archivo de instrucciones: se llevaba los
+  guards y nada más, así que podía ser detenido pero no sabía que existía un protocolo, un catálogo de
+  cargos ni equipos. No existe un `CODEX.md`: `AGENTS.md` es el nombre que Codex lee, compartido entre
+  herramientas, y por eso en modo embedded no se instala —el de la empresa ya está ahí y manda—.
+
+### Corregido
+
+- **Las rutas de los adaptadores se resuelven contra la carpeta donde se abre la herramienta.** Al
+  mover la instalación a la raíz de la compañía quedaron apuntando al lugar equivocado: `@AGENTS.md`
+  y `@planning/PROTOCOL.md` no resolvían, y los workflows buscaban `planning/` donde no estaba. Ahora
+  cada fuente marca el lugar con `{{OPS_DIR}}` y `install` lo completa; `doctor` compara contra lo
+  mismo que `install` escribe.
+- `tools/ops.js` exporta la raíz ops, que ya calculaba y no usaba. Invocado desde la carpeta de la
+  compañía —`node <empresa>-ops/tools/ops.js team list`—, `agents list` y `team list` resolvían contra
+  el cwd y devolvían **vacío en vez de fallar**. `team` además no aceptaba una raíz de ningún modo.
+
 ## [0.5.0] - 2026-08-15
 
 ### Cambiado

package/automatization/runners/antigravity/rules/cauce.md

@@ -1,6 +1,6 @@
 # Cauce
 
-Lee y cumple `AGENTS.md` y `planning/PROTOCOL.md` antes de ejecutar trabajo. `planning/WIP.md` es el mutex de
-ejecución y `planning/AWAITING_REVIEW.md` bloquea una corrida nueva. No promociones ideas desde INBOX, no
+Lee y cumple `AGENTS.md` y `{{OPS_DIR}}planning/PROTOCOL.md` antes de ejecutar trabajo. `{{OPS_DIR}}planning/WIP.md` es el mutex de
+ejecución y `{{OPS_DIR}}planning/AWAITING_REVIEW.md` bloquea una corrida nueva. No promociones ideas desde INBOX, no
 inventes aprobaciones o credenciales y no hagas push ni deploy. Cierra cada tarea con verificación real y
 evidencia en DONE.

package/automatization/runners/claude/CLAUDE.md

@@ -1,11 +1,11 @@
 # Cauce para Claude Code
 
-@AGENTS.md
-@planning/PROTOCOL.md
+@{{OPS_DIR}}AGENTS.md
+@{{OPS_DIR}}planning/PROTOCOL.md
 
 Los hooks de `.claude/settings.json` son obligatorios. Usa `/team` para evaluar si una intención es viable
 y proponer una épica, y `/autobuild` para ejecutar trabajo ya promovido; `/integration-sync` e
 `/integration-promote` gestionan staging local sin escritura remota. Ninguno promueve al BACKLOG.
 
-Antes de iniciar, respeta `planning/AWAITING_REVIEW.md` y el mutex de `planning/WIP.md`. Si el protocolo y
-un workflow difieren, manda el protocolo y la diferencia se registra en `planning/INBOX.md`.
+Antes de iniciar, respeta `{{OPS_DIR}}planning/AWAITING_REVIEW.md` y el mutex de `{{OPS_DIR}}planning/WIP.md`. Si el protocolo y
+un workflow difieren, manda el protocolo y la diferencia se registra en `{{OPS_DIR}}planning/INBOX.md`.

package/automatization/runners/claude/settings.json

@@ -4,20 +4,20 @@
       {
         "matcher": "Bash",
         "hooks": [
-          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/automatization/hooks/guard-shell.sh" }
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-shell.sh" }
         ]
       },
       {
         "matcher": "Edit|Write",
         "hooks": [
-          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/automatization/hooks/guard-files.sh" }
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-files.sh" }
         ]
       }
     ],
     "Stop": [
       {
         "hooks": [
-          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/automatization/hooks/guard-planning-drift.sh" }
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/{{OPS_DIR}}automatization/hooks/guard-planning-drift.sh" }
         ]
       }
     ]

package/automatization/runners/codex/AGENTS.md

@@ -0,0 +1,47 @@
+# Cauce para Codex
+
+`{{OPS_DIR}}AGENTS.md` tiene las reglas del sistema y `{{OPS_DIR}}planning/PROTOCOL.md` es la fuente de
+verdad del proceso. Leelos antes de trabajar: acá sólo está lo específico de este runner.
+
+> Codex lee el `AGENTS.md` de la raíz, que es un nombre compartido entre herramientas. Cuando el repo
+> ops **es** la raíz, este archivo no se instala: el `AGENTS.md` de la empresa ya está ahí y manda.
+
+Los hooks de `.codex/hooks/hooks.json` son obligatorios y bloquean por su cuenta. Codex no ejecuta los
+workflows JS de Claude —son referencia, no un runtime compatible—, así que el recorrido se hace fase por
+fase siguiendo el protocolo.
+
+`{{OPS_DIR}}planning/WIP.md` es el mutex: una sola tarea activa. `{{OPS_DIR}}planning/AWAITING_REVIEW.md`
+bloquea una corrida nueva hasta que un humano revise. Nada se promueve desde `INBOX.md` sin aprobación.
+
+Antes de cerrar, corré `node {{OPS_DIR}}tools/ops.js check {{OPS_DIR}}planning`.
+
+## Los cargos
+
+El catálogo está en `{{OPS_DIR}}node_modules/@ingeniomaps/cauce/agents/` —o en
+`{{OPS_DIR}}.ops/agents/` si este repo no usa npm— y los propios de la empresa en
+`{{OPS_DIR}}agents/`, que mandan sobre los del sistema con el mismo nombre.
+
+Cada cargo tiene un `SKILL.md` con su contrato: cuándo actúa, qué decide, qué no le corresponde y cuál es
+su entrega mínima. Para ver la lista con una línea por cargo:
+
+```bash
+node {{OPS_DIR}}tools/ops.js agents list
+```
+
+Leé el `SKILL.md` del cargo que corresponda antes de actuar en su terreno, y respetá sus límites. Lo que
+ese cargo debe saber de esta empresa está en `{{OPS_DIR}}organization/roles/<slug>.md`.
+
+## Los equipos
+
+Un equipo es una secuencia de cargos con etapas y exit gates, para evaluar una intención antes de que
+exista una épica. Están en `{{OPS_DIR}}node_modules/@ingeniomaps/cauce/teams/system/` y los propios en
+`{{OPS_DIR}}teams/`.
+
+```bash
+node {{OPS_DIR}}tools/ops.js team list
+node {{OPS_DIR}}tools/ops.js team show <slug>
+```
+
+Ningún equipo promueve trabajo al BACKLOG: escribe la épica o el informe y para.
+
+Nunca omitas aprobaciones, inventes credenciales, escribas en un sistema remoto, hagas push o deploy.

package/automatization/runners/codex/hooks.json

@@ -4,20 +4,20 @@
       {
         "matcher": "shell|unified_exec",
         "hooks": [
-          { "type": "command", "command": "automatization/hooks/guard-shell.sh" }
+          { "type": "command", "command": "{{OPS_DIR}}automatization/hooks/guard-shell.sh" }
         ]
       },
       {
         "matcher": "apply_patch|files",
         "hooks": [
-          { "type": "command", "command": "automatization/hooks/guard-files.sh" }
+          { "type": "command", "command": "{{OPS_DIR}}automatization/hooks/guard-files.sh" }
         ]
       }
     ],
     "SessionEnd": [
       {
         "hooks": [
-          { "type": "command", "command": "automatization/hooks/guard-planning-drift.sh" }
+          { "type": "command", "command": "{{OPS_DIR}}automatization/hooks/guard-planning-drift.sh" }
         ]
       }
     ]

package/automatization/runners/codex/manifest.json

@@ -6,7 +6,12 @@
     "source": "hooks.json",
     "target": ".codex/hooks/hooks.json"
   },
-  "instructions": [],
+  "instructions": [
+    {
+      "source": "AGENTS.md",
+      "target": "AGENTS.md"
+    }
+  ],
   "artifacts": [],
   "capabilities": {
     "nativeHooks": true,

package/automatization/runners/gemini/GEMINI.md

@@ -1,12 +1,12 @@
 # Cauce para Gemini CLI
 
-@AGENTS.md
-@planning/PROTOCOL.md
+@{{OPS_DIR}}AGENTS.md
+@{{OPS_DIR}}planning/PROTOCOL.md
 
-`planning/PROTOCOL.md` es la fuente de verdad. Ejecuta `/ops:autobuild` fase por fase; los workflows JS de
-Claude son referencia, no un runtime compatible. `planning/WIP.md` es el mutex y
-`planning/AWAITING_REVIEW.md` bloquea una corrida nueva.
+`{{OPS_DIR}}planning/PROTOCOL.md` es la fuente de verdad. Ejecuta `/ops:autobuild` fase por fase; los workflows JS de
+Claude son referencia, no un runtime compatible. `{{OPS_DIR}}planning/WIP.md` es el mutex y
+`{{OPS_DIR}}planning/AWAITING_REVIEW.md` bloquea una corrida nueva.
 
 Gemini no tiene guards nativos configurados por este toolkit. Antes de cada commit ejecuta los wrappers de
-`automatization/hooks/` como prechecks y al cerrar ejecuta `node tools/ops.js check planning`. Nunca omitas
+`{{OPS_DIR}}automatization/hooks/` como prechecks y al cerrar ejecuta `node {{OPS_DIR}}tools/ops.js check planning`. Nunca omitas
 aprobaciones, inventes credenciales, escribas remoto, hagas push/deploy o promociones trabajo desde INBOX.

package/automatization/workflows/autobuild.js

@@ -10,7 +10,10 @@ export const meta = {
   ].map((title) => ({ title, detail: `Fase ${title} del protocolo agnóstico` })),
 }
 
-const ROOT = process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || '.'
+// El prefijo lo completa `automation install`: en modo sidecar la herramienta se abre en la carpeta
+// de la compañía y la raíz ops es uno de sus hijos, no la carpeta misma.
+const ROOT = (process.env.OPS_ROOT
+  || `${process.env.CLAUDE_PROJECT_DIR || '.'}/{{OPS_DIR}}`).replace(/\/+$/, '')
 const CONFIG = `${ROOT}/ops.config.json`
 const P = `${ROOT}/planning`
 const BACKLOG = `${P}/BACKLOG.md`

package/automatization/workflows/integrations/promote.js

@@ -10,7 +10,10 @@ export const meta = {
   ],
 }
 
-const ROOT = process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || '.'
+// El prefijo lo completa `automation install`: en modo sidecar la herramienta se abre en la carpeta
+// de la compañía y la raíz ops es uno de sus hijos, no la carpeta misma.
+const ROOT = (process.env.OPS_ROOT
+  || `${process.env.CLAUDE_PROJECT_DIR || '.'}/{{OPS_DIR}}`).replace(/\/+$/, '')
 const PROVIDER = process.env.OPS_INTEGRATION_PROVIDER || ''
 const KEY = process.env.OPS_INTEGRATION_KEY || ''
 const RESULT = {

package/automatization/workflows/integrations/sync.js

@@ -10,7 +10,10 @@ export const meta = {
   ],
 }
 
-const ROOT = process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || '.'
+// El prefijo lo completa `automation install`: en modo sidecar la herramienta se abre en la carpeta
+// de la compañía y la raíz ops es uno de sus hijos, no la carpeta misma.
+const ROOT = (process.env.OPS_ROOT
+  || `${process.env.CLAUDE_PROJECT_DIR || '.'}/{{OPS_DIR}}`).replace(/\/+$/, '')
 const REQUESTED = process.env.OPS_INTEGRATION_PROVIDER || ''
 const RESULT = {
   type: 'object', additionalProperties: false, required: ['passed', 'provider', 'details'],

package/automatization/workflows/team.js

@@ -15,7 +15,10 @@ export const meta = {
   ],
 }
 
-const ROOT = process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || '.'
+// El prefijo lo completa `automation install`: en modo sidecar la herramienta se abre en la carpeta
+// de la compañía y la raíz ops es uno de sus hijos, no la carpeta misma.
+const ROOT = (process.env.OPS_ROOT
+  || `${process.env.CLAUDE_PROJECT_DIR || '.'}/{{OPS_DIR}}`).replace(/\/+$/, '')
 const P = `${ROOT}/planning`
 const ROADMAP = `${P}/roadmap`
 const HUMAN = `${P}/HUMAN_ACTIONS.md`

package/engine/automation/index.js

@@ -122,13 +122,20 @@ function resolveItem(paths, root, name, item) {
   }
 }
 
-// La configuración del runner nombra cada guard por ruta relativa a donde se abre la herramienta.
-// Si eso ya no es la raíz ops, hay que reescribir el prefijo o el runner buscaría los guards en la
-// carpeta equivocada. Se hace en un solo lugar: `install` lo escribe y `doctor` compara contra esto.
+// Todo lo que un adaptador copia —configuración, instrucciones, workflows— nombra rutas relativas a
+// la carpeta donde se abre la herramienta. Cuando la raíz ops no es esa carpeta, cada una necesita el
+// prefijo. El marcador es explícito en la fuente en vez de adivinarse con reemplazos de texto:
+// `{{OPS_DIR}}` significa "acá va la raíz ops, o nada si coinciden".
+//
+// Un solo render, y `install` escribe exactamente lo que `doctor` compara.
+const OPS_DIR = '{{OPS_DIR}}'
+
+function render(file, prefix) {
+  return fs.readFileSync(file, 'utf8').split(OPS_DIR).join(prefix)
+}
+
 function runnerConfig(paths, root) {
-  const raw = fs.readFileSync(paths.configSource, 'utf8')
-  const prefix = opsPrefix(root)
-  return JSON.parse(prefix ? raw.split('automatization/hooks/').join(`${prefix}automatization/hooks/`) : raw)
+  return JSON.parse(render(paths.configSource, opsPrefix(root)))
 }
 
 // Cargos del catálogo, con el frontmatter que el runner indexa para elegir a quién invocar.
@@ -368,11 +375,15 @@ function doctor(root, name, output = console) {
   }
   for (const item of runner.instructions || []) {
     const resolved = { item, ...resolveItem(paths, root, name, item) }
+    // `AGENTS.md` es un nombre compartido entre herramientas y la instancia ya tiene el suyo: en
+    // modo embedded el archivo del runner y el de la empresa son el mismo, y pedirle que se
+    // referencie a sí mismo no significa nada.
+    const propio = path.basename(resolved.target) === 'AGENTS.md'
     if (!fs.existsSync(resolved.target)) errors.push(`falta ${item.target}`)
-    else if (!fs.readFileSync(resolved.target, 'utf8').includes('AGENTS.md')) {
+    else if (!propio && !fs.readFileSync(resolved.target, 'utf8').includes('AGENTS.md')) {
       warnings.push(`${item.target}: no referencia AGENTS.md; verifica las reglas globales`)
     }
-    if (deliveryState(M.readRunners(root), name, resolved) === 'desactualizado') {
+    if (deliveryState(M.readRunners(root), name, resolved, opsPrefix(root)) === 'desactualizado') {
       warnings.push(`${item.target}: Cauce trae una versión más nueva y vos no lo tocaste; reinstalá`)
     }
   }
@@ -381,7 +392,7 @@ function doctor(root, name, output = console) {
   const recorded = M.readRunners(root)
   for (const item of runner.artifacts || []) {
     const resolved = { item, ...resolveItem(paths, root, name, item) }
-    const situacion = deliveryState(recorded, name, resolved)
+    const situacion = deliveryState(recorded, name, resolved, opsPrefix(root))
     if (situacion === 'nuevo') errors.push(`falta ${item.target}`)
     else if (situacion === 'desactualizado') {
       warnings.push(`${item.target}: hay una versión más nueva en Cauce; reinstalá el adaptador`)
@@ -432,10 +443,10 @@ function deliveryKey(name, target) {
 //
 // Sin el registro de entrega, `desactualizado` y `ajeno` se ven igual. `install` resolvía esa duda
 // conservando siempre, así que ninguna mejora del toolkit llegaba nunca a un runner ya instalado.
-function deliveryState(recorded, name, resolved) {
+function deliveryState(recorded, name, resolved, prefix = '') {
   if (!fs.existsSync(resolved.target)) return 'nuevo'
   const current = M.digest(resolved.target)
-  if (current === M.digest(resolved.source)) return 'al día'
+  if (current === M.digestText(render(resolved.source, prefix))) return 'al día'
   const delivered = recorded[deliveryKey(name, resolved.item.target)]
   return delivered && delivered === current ? 'desactualizado' : 'ajeno'
 }
@@ -458,7 +469,8 @@ function install(root, name, output = console, options = {}) {
   for (const resolved of resolvedItems) F.assertNoSymlinkPath(paths.install, resolved.target)
 
   const recorded = M.readRunners(root)
-  const state = new Map(resolvedItems.map((resolved) => [resolved, deliveryState(recorded, name, resolved)]))
+  const prefix = opsPrefix(root)
+  const state = new Map(resolvedItems.map((r) => [r, deliveryState(recorded, name, r, prefix)]))
   // Un archivo de instrucciones es del proyecto y se conserva; uno ejecutable es del toolkit y se
   // reemplaza. Editarlo detiene la instalación antes de pisarlo, igual que hace `upgrade`.
   const editados = resolvedItems.filter((resolved) => {
@@ -480,7 +492,7 @@ function install(root, name, output = console, options = {}) {
   // Dónde aterrizó, no sólo qué archivo: en sidecar el destino no es el repo desde el que se corrió
   // el comando, y descubrirlo por sorpresa es la diferencia entre confiar y adivinar.
   if (paths.install !== root) {
-    output.log(`  ${name}: el runner se abre en ${paths.install} — ahí quedan .claude/ y CLAUDE.md`)
+    output.log(`  ${name}: el runner se abre en ${paths.install} — ahí queda su configuración`)
   }
   output.log(`✓ ${name}: configuración instalada en ${runner.config.target}`)
   const entregado = { ...recorded }
@@ -493,7 +505,7 @@ function install(root, name, output = console, options = {}) {
       output.log(`= ${name}: ${resolved.item.target} ya está al día`)
     } else {
       fs.mkdirSync(path.dirname(resolved.target), { recursive: true })
-      fs.copyFileSync(resolved.source, resolved.target)
+      F.atomicWrite(resolved.target, render(resolved.source, opsPrefix(root)))
       const verbo = situacion === 'nuevo' ? 'instalado' : 'actualizado'
       output.log(`✓ ${name}: ${verbo} ${resolved.item.target}`)
     }

package/engine/cli/ops.js

@@ -594,9 +594,15 @@ function upgrade(dir) {
 
 // Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
 // reimplemente el recorrido del catálogo.
+// La raíz ops de un comando que no la recibe. El shim `tools/ops.js` la exporta porque sabe dónde
+// vive: sin eso, invocarlo desde otra carpeta —lo normal en sidecar— la resolvía contra el cwd.
+function opsRoot(dir) {
+  return path.resolve(dir || process.env.OPS_ROOT || '.')
+}
+
 function agents(action, dir) {
   if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
-  const root = path.resolve(dir || '.')
+  const root = opsRoot(dir)
   const roles = AG.list(root)
   if (process.argv.includes('--json')) {
     // `path` viene resuelto: quien consuma esto no debería reconstruir dónde ganó la precedencia.
@@ -685,7 +691,7 @@ async function integration(action, rootArg, provider, key) {
 }
 
 function automation(action, rootArg, runnerName) {
-  const root = path.resolve(rootArg || '.')
+  const root = opsRoot(rootArg)
   if (action === 'list-hooks') return A.listHooks()
   if (action === 'list') {
     for (const name of A.RUNNER_NAMES) {
@@ -756,12 +762,12 @@ function evaluate(agent) {
 
 function team(action, slug) {
   if (action === 'list') {
-    for (const name of T.list(process.cwd())) console.log(name)
+    for (const name of T.list(opsRoot())) console.log(name)
     return
   }
   if (!['check', 'show'].includes(action)) fail(`Acción de team desconocida: ${action || '(vacía)'}`, 2)
   try {
-    const result = T.validate(process.cwd(), slug)
+    const result = T.validate(opsRoot(), slug)
     for (const error of result.errors) console.error(`✗ ${error}`)
     if (result.errors.length) fail(`${slug}: ${result.errors.length} error(es)`, 1)
     if (action === 'show') {

package/engine/core/manifest.js

@@ -13,10 +13,12 @@ const path = require('node:path')
 
 const FILE = path.join('.cauce', 'manifest.json')
 
+function digestText(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16)
+}
+
 function digest(file) {
-  try {
-    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex').slice(0, 16)
-  } catch { return '' }
+  try { return digestText(fs.readFileSync(file)) } catch { return '' }
 }
 
 // Dos secciones porque son dos entregas distintas: `files` es lo que se materializó dentro de la
@@ -80,4 +82,4 @@ function edited(root, relative, files) {
   })
 }
 
-module.exports = { FILE, digest, edited, prune, read, readRunners, record, write }
+module.exports = { FILE, digest, digestText, edited, prune, read, readRunners, record, write }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "type": "commonjs",
   "bin": {

package/template/tools/ops.js

@@ -8,6 +8,12 @@
 const path = require('path')
 
 const root = path.join(__dirname, '..')
+
+// El shim sabe dónde vive; quien lo invoca, no. En modo sidecar se lo llama desde la carpeta de la
+// compañía —`node <empresa>-ops/tools/ops.js …`— y sin esto cada comando resolvería su raíz contra
+// el cwd: `agents list` y `team list` devolvían vacío en vez de fallar.
+process.env.OPS_ROOT = process.env.OPS_ROOT || root
+
 const candidates = [
   () => require.resolve('@ingeniomaps/cauce/engine/cli/ops.js', { paths: [root] }),
   () => require.resolve(path.join(root, '.ops', 'engine', 'cli', 'ops.js')),