@ingeniomaps/cauce 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,53 @@ 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.0] - 2026-08-15
+
+### Cambiado
+
+- **Los adaptadores de runner y los workflows tampoco se copian al proyecto.** Cierran el mismo
+  criterio que ya rige para cargos y equipos: los lee el motor, no la empresa. `automation install`,
+  `check` y `doctor` los resuelven desde la dependencia npm, o desde `.ops/` cuando el repo no usa
+  npm. Nadie los editaba —la lista de runners es cerrada, así que una empresa ni siquiera podía
+  agregar el suyo— y `automatization/workflows/` estaba además duplicado dentro de cada instancia,
+  idéntico a lo que `automation install` deja en `.claude/workflows/`.
+- `upgrade` retira `automatization/runners/` y `automatization/workflows/` de las instancias que los
+  arrastran de una versión anterior. Un guard propio en `automatization/hooks/` no se toca.
+- `automatization/hooks/` se queda en el proyecto, y esto no es una excepción arbitraria: la
+  configuración de cada runner nombra cada guard por ruta literal y no sabe resolver en cascada. Ahí
+  es también donde una empresa agrega el suyo.
+
+- **En modo `sidecar`, `automation install` instala en la carpeta de la compañía, no dentro del repo
+  ops.** El repo ops coordina varios repos de producto y es hermano de ellos, así que instalar el
+  runner adentro lo dejaba sin ver una sola línea de código: el dev que abría su herramienta donde
+  está el código no tenía guards, ni cargos, ni workflows. Las rutas de guards y los punteros de cada
+  cargo se reescriben con el prefijo del repo ops al instalar.
+
+### Corregido
+
+- **Una mejora del toolkit en el wiring ahora llega a un runner ya instalado.** `install` conservaba
+  cualquier archivo existente, así que un workflow o un `CLAUDE.md` mejorado río arriba no llegaba
+  nunca. Peor: si el archivo difería, `install` fallaba —`existe y difiere de la fuente canónica`— y
+  `doctor` lo reportaba como error, dejando a la empresa sin salida salvo borrar a mano. Ahora el
+  registro de entrega distingue las dos cosas que antes se veían iguales: lo que la empresa editó se
+  conserva o detiene la instalación, y lo que sólo cambió río arriba se actualiza.
+- `automation check` compara los guards de la instancia contra los del paquete. Existir y ser
+  ejecutable no alcanzaba: un guard viejo no falla, **deja de proteger en silencio**, y `check`,
+  `doctor` y `upgrade` daban verde igual porque sólo miraban el número de versión. Ahora bloquea la
+  instalación del runner y dice qué correr; distingue además el guard que la empresa editó del que
+  simplemente quedó atrás.
+- `upgrade` recuerda reinstalar los runners: el wiring vive fuera de la instancia y lo escribe otro
+  comando, así que sin el aviso una mejora se quedaba en el paquete.
+- Los guards resuelven la raíz ops por su cuenta. `findOpsRoot` sólo sube por el árbol, y en sidecar
+  la raíz ops es un *hermano* de los repos de producto: desde ahí no la encontraba, devolvía vacío y
+  el guard permitía todo **en silencio**. `run-hook.sh` ya sabía dónde vive; ahora lo exporta.
+- `automatization/README.md` y `automatization/AGENTS.md` se actualizan con el toolkit. Los escribe
+  Cauce y envejecían en cada instancia: después de retirar `runners/` y `workflows/`, el README de la
+  empresa seguía explicando cómo usar dos carpetas que ya no existían.
+- El registro de entrega olvida lo que ya no está en disco. Sólo crecía: al retirar una ruta dejaba
+  su digest para siempre, y el día que un nombre se reutilizara la entrega nueva se habría leído como
+  una edición local y detenido la actualización.
+
 ## [0.4.1] - 2026-08-15
 
 ### Corregido

package/README.md

@@ -157,10 +157,11 @@ Cada colección adaptable separa lo que actualiza el toolkit de lo que escribe e
 | `teams/` | composiciones que vienen con Cauce | los equipos propios |
 | `agents/<tipo>/` | *(en el paquete, no se copia)* | los cargos propios |
 
-`automatization/hooks/` y `automatization/runners/` no tienen `system/`: son runtime que se reemplaza
-entero. No hace falta, porque lo que un proyecto necesita ya funciona sin editarlos — un guard propio
-convive y sobrevive, y desactivar uno del toolkit es quitarlo de la configuración del runner, que es del
-proyecto. Editar uno existente detiene el `upgrade` antes de pisarlo.
+`automatization/hooks/` no tiene `system/`: es runtime que se reemplaza entero. No hace falta, porque lo
+que un proyecto necesita ya funciona sin editarlo — un guard propio convive y sobrevive, y desactivar uno
+del toolkit es quitarlo de la configuración del runner, que es del proyecto. Editar uno existente detiene
+el `upgrade` antes de pisarlo. Los hooks se quedan en el proyecto porque esa configuración los nombra por
+ruta literal; los adaptadores de runner y los workflows, que sólo lee el motor, viajan en el paquete.
 
 Un archivo propio con el mismo nombre o ID que uno de `system/` lo reemplaza: el del proyecto manda y
 `check` lo reporta como override explícito. Así una mejora del proceso no obliga a forkear el archivo,

package/automatization/hooks/run-hook.sh

@@ -4,6 +4,10 @@ set -u
 hook_name=${1:-}
 hook_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 ops_root=$(CDPATH= cd -- "$hook_dir/../.." && pwd)
+# El guard sabe dónde vive; quien lo invoca, no necesariamente. En modo sidecar la herramienta se
+# abre en la carpeta de la compañía y la raíz ops es un hermano, que ninguna búsqueda hacia arriba
+# encuentra: sin esto el guard no halla `ops.config.json` y deja pasar todo en silencio.
+export OPS_ROOT="$ops_root"
 # Mismo orden que tools/ops.js: primero la dependencia npm, después la copia local, y por último
 # el propio repositorio del toolkit. Un guard que no encuentra su motor bloquea, nunca permite.
 runner=""

package/engine/automation/index.js

@@ -8,14 +8,30 @@ const H = require('../hooks/run')
 const P = require('../planning/parser')
 const catalog = require('../agents/catalog')
 const O = require('../core/ownership')
+const M = require('../core/manifest')
 
 const RUNNER_NAMES = ['claude', 'codex', 'gemini', 'antigravity']
 
+// Adaptadores y workflows viven en el paquete, no en la instancia: son definiciones que el motor
+// consume y que ninguna empresa edita —`RUNNER_NAMES` es cerrado, así que ni siquiera puede agregar
+// uno propio—. Los hooks sí se quedan en el proyecto: la configuración del runner los nombra por
+// ruta literal y no sabe resolver en cascada.
+// Se busca por `runners/` y no por `automatization/`: toda instancia tiene el segundo —ahí viven sus
+// hooks— y encontrarlo daría por buena una dependencia sin instalar.
+function packagedAutomation(root) {
+  const runners = O.packagePath(root, path.join('automatization', 'runners'))
+  return runners ? path.dirname(runners) : ''
+}
+
 function runnerManifest(root, name) {
   if (!RUNNER_NAMES.includes(name)) {
     throw new Error(`runner debe ser ${RUNNER_NAMES.join(', ')}`)
   }
-  const file = path.join(root, 'automatization', 'runners', name, 'manifest.json')
+  const packaged = packagedAutomation(root)
+  if (!packaged) {
+    throw new Error('no encuentro automatization/: instalá la dependencia o restaurá .ops/')
+  }
+  const file = path.join(packaged, 'runners', name, 'manifest.json')
   try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch (error) {
     throw new Error(`${name}: manifest inválido (${error.message})`)
   }
@@ -57,20 +73,38 @@ function includesConfig(actual, expected) {
   return actual === expected
 }
 
+// Dónde abre el dev su herramienta, que no siempre es la raíz ops. En modo sidecar el repo ops es
+// un hermano de los repos de producto: `aparatejo-ops/` coordina, `aparatejo/` es lo que se abre.
+// Instalar dentro del sidecar dejaría al runner sin ver una sola línea de código.
+function installRoot(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, instalar donde está */ }
+  return root
+}
+
+// Cómo se nombra la raíz ops desde ahí: `aparatejo-ops/` en sidecar, vacío cuando coinciden.
+function opsPrefix(root) {
+  const relative = path.relative(installRoot(root), root)
+  return relative ? `${relative.split(path.sep).join('/')}/` : ''
+}
+
 function runnerPaths(root, name, runner) {
-  const automationRoot = path.join(root, 'automatization')
-  const sourceDir = path.join(root, 'automatization', 'runners', name)
+  const automationRoot = packagedAutomation(root)
+  const sourceDir = path.join(automationRoot, 'runners', name)
+  const install = installRoot(root)
   const configSource = F.assertWithin(
     sourceDir,
     path.resolve(sourceDir, runner.config.source),
     `${name}: config.source`,
   )
   const configTarget = F.assertWithin(
-    root,
-    path.resolve(root, runner.config.target),
+    install,
+    path.resolve(install, runner.config.target),
     `${name}: config.target`,
   )
-  return { automationRoot, sourceDir, configSource, configTarget }
+  return { automationRoot, sourceDir, configSource, configTarget, install }
 }
 
 function resolveItem(paths, root, name, item) {
@@ -80,16 +114,30 @@ function resolveItem(paths, root, name, item) {
       path.resolve(paths.sourceDir, item.source),
       `${name}: source`,
     ),
-    target: F.assertWithin(root, path.resolve(root, item.target), `${name}: target`),
+    target: F.assertWithin(
+      paths.install,
+      path.resolve(paths.install, item.target),
+      `${name}: target`,
+    ),
   }
 }
 
+// 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.
+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)
+}
+
 // Cargos del catálogo, con el frontmatter que el runner indexa para elegir a quién invocar.
 function roleCatalog(root) {
   return catalog.list(root)
     .map((role) => {
       const field = P.frontmatter(fs.readFileSync(path.join(role.dir, 'SKILL.md'), 'utf8'))
-      return { ...role, reference: path.relative(root, role.dir), description: field('description') }
+      const reference = path.relative(installRoot(root), role.dir).split(path.sep).join('/')
+      return { ...role, reference, description: field('description') }
     })
     .filter((role) => role.description)
 }
@@ -115,11 +163,12 @@ Respetá los límites de ese contrato y las reglas de \`AGENTS.md\`. Generado po
 
 function installRoleSkills(root, runner, output) {
   if (!runner.capabilities.nativeSkills || !runner.roleSkills) return 0
-  const base = F.assertWithin(root, path.resolve(root, runner.roleSkills), `${runner.name}: roleSkills`)
+  const install = installRoot(root)
+  const base = F.assertWithin(install, path.resolve(install, runner.roleSkills), `${runner.name}: roleSkills`)
   const roles = roleCatalog(root)
   for (const role of roles) {
     const file = path.join(base, role.slug, 'SKILL.md')
-    F.assertNoSymlinkPath(root, file)
+    F.assertNoSymlinkPath(install, file)
     F.atomicWrite(file, roleSkill(role))
   }
   if (roles.length) output.log(`✓ ${runner.name}: ${roles.length} cargo(s) disponibles en ${runner.roleSkills}`)
@@ -141,6 +190,30 @@ function hasHooks(config) {
   })
 }
 
+// Guards de la instancia que ya no coinciden con los del paquete. Existir y ser ejecutable no
+// alcanza: un guard viejo no falla, deja de proteger sin decir nada. La instancia declaraba una
+// versión y nadie comprobaba que su runtime fuera realmente esa.
+function staleHooks(root) {
+  const packaged = packagedAutomation(root)
+  if (!packaged) return []
+  const shipped = path.join(packaged, 'hooks')
+  const mine = path.join(root, 'automatization', 'hooks')
+  const recorded = M.read(root)
+  const stale = []
+  let names = []
+  try { names = fs.readdirSync(shipped) } catch { return [] }
+  for (const file of names) {
+    const local = path.join(mine, file)
+    // Los que faltan ya los reporta el chequeo de arriba; acá sólo interesa el que quedó atrás.
+    if (!fs.existsSync(local)) continue
+    const current = M.digest(local)
+    if (current === M.digest(path.join(shipped, file))) continue
+    const delivered = recorded[`automatization/hooks/${file}`]
+    stale.push({ file, edited: Boolean(delivered) && delivered !== current })
+  }
+  return stale
+}
+
 function check(root) {
   const errors = []
   const hookDir = path.join(root, 'automatization', 'hooks')
@@ -176,11 +249,19 @@ function check(root) {
   }
   const workflows = ['autobuild.js', 'team.js', path.join('integrations', 'sync.js')]
   workflows.push(path.join('integrations', 'promote.js'))
+  const packaged = packagedAutomation(root)
   for (const name of workflows) {
-    if (!fs.existsSync(path.join(root, 'automatization', 'workflows', name))) {
-      errors.push(`falta automatization/workflows/${name}`)
+    if (!packaged || !fs.existsSync(path.join(packaged, 'workflows', name))) {
+      errors.push(`falta automatization/workflows/${name}: instalá la dependencia o restaurá .ops/`)
     }
   }
+  for (const { file, edited } of staleHooks(root)) {
+    errors.push(edited
+      ? `automatization/hooks/${file}: lo editaste y es del toolkit; agregá un guard propio al lado `
+        + 'o descartá tu cambio con `cauce upgrade --force`'
+      : `automatization/hooks/${file}: quedó atrás del paquete y ya no protege lo que dice; `
+        + 'corré `cauce upgrade` antes de instalar el runner')
+  }
   for (const name of RUNNER_NAMES) validateRunner(root, name, errors)
   return errors
 }
@@ -194,7 +275,7 @@ function validateRunner(root, name, errors) {
       return
     }
     const paths = runnerPaths(root, name, runner)
-    const config = JSON.parse(fs.readFileSync(paths.configSource, 'utf8'))
+    const config = runnerConfig(paths, root)
     if (runner.capabilities.nativeHooks && !hasHooks(config)) {
       errors.push(`${name}: declara hooks nativos pero no los configura`)
     }
@@ -272,7 +353,7 @@ function doctor(root, name, output = console) {
   const errors = []
   const warnings = []
   try {
-    const expected = JSON.parse(fs.readFileSync(paths.configSource, 'utf8'))
+    const expected = runnerConfig(paths, root)
     const actual = JSON.parse(fs.readFileSync(paths.configTarget, 'utf8'))
     if (!includesConfig(actual, expected)) {
       errors.push(`${runner.config.target}: configuración instalada incompleta o divergente`)
@@ -286,18 +367,27 @@ function doctor(root, name, output = console) {
     errors.push(`${runner.config.target}: ${error.message}`)
   }
   for (const item of runner.instructions || []) {
-    const resolved = resolveItem(paths, root, name, item)
+    const resolved = { item, ...resolveItem(paths, root, name, item) }
     if (!fs.existsSync(resolved.target)) errors.push(`falta ${item.target}`)
     else if (!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') {
+      warnings.push(`${item.target}: Cauce trae una versión más nueva y vos no lo tocaste; reinstalá`)
+    }
   }
+  // Divergir no es un error: puede ser una mejora río arriba esperando reinstalación. Reportarlo
+  // como error dejaba a la empresa sin salida, porque `install` tampoco lo actualizaba.
+  const recorded = M.readRunners(root)
   for (const item of runner.artifacts || []) {
-    const resolved = resolveItem(paths, root, name, item)
-    if (!fs.existsSync(resolved.target)) errors.push(`falta ${item.target}`)
-    else if (fs.readFileSync(resolved.source, 'utf8')
-      !== fs.readFileSync(resolved.target, 'utf8')) {
-      errors.push(`${item.target}: difiere de la fuente canónica`)
+    const resolved = { item, ...resolveItem(paths, root, name, item) }
+    const situacion = deliveryState(recorded, name, resolved)
+    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`)
+    } else if (situacion === 'ajeno') {
+      warnings.push(`${item.target}: lo editaste y es del toolkit; `
+        + 'agregá lo tuyo al lado o reinstalá con --force para volver a la versión de Cauce')
     }
   }
   // Un cargo que quedó fuera, o cuya descripción cambió en el catálogo, deja al runner eligiendo
@@ -306,7 +396,7 @@ function doctor(root, name, output = console) {
     const missing = []
     const stale = []
     for (const role of roleCatalog(root)) {
-      const file = path.join(root, runner.roleSkills, role.slug, 'SKILL.md')
+      const file = path.join(paths.install, runner.roleSkills, role.slug, 'SKILL.md')
       if (!fs.existsSync(file)) missing.push(role.slug)
       else if (fs.readFileSync(file, 'utf8') !== roleSkill(role)) stale.push(role.slug)
     }
@@ -327,12 +417,35 @@ function doctor(root, name, output = console) {
   return { runner, errors, warnings }
 }
 
-function install(root, name, output = console) {
+// Clave de entrega de un archivo del adaptador. Va en su propia sección del manifiesto porque puede
+// caer fuera de la instancia: en sidecar el wiring vive en la carpeta de la compañía.
+function deliveryKey(name, target) {
+  return `${name}/${target.split(path.sep).join('/')}`
+}
+
+// En qué estado quedó un archivo que este adaptador entregó alguna vez.
+//
+//   nuevo          no existe todavía
+//   al día         idéntico a lo que trae Cauce
+//   desactualizado la empresa no lo tocó, pero río arriba cambió
+//   ajeno          difiere de lo entregado: alguien lo editó acá
+//
+// 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) {
+  if (!fs.existsSync(resolved.target)) return 'nuevo'
+  const current = M.digest(resolved.target)
+  if (current === M.digest(resolved.source)) return 'al día'
+  const delivered = recorded[deliveryKey(name, resolved.item.target)]
+  return delivered && delivered === current ? 'desactualizado' : 'ajeno'
+}
+
+function install(root, name, output = console, options = {}) {
   const runner = runnerManifest(root, name)
   const errors = check(root)
   if (errors.length) throw new Error(`La automatización no es instalable:\n- ${errors.join('\n- ')}`)
   const paths = runnerPaths(root, name, runner)
-  const incoming = JSON.parse(fs.readFileSync(paths.configSource, 'utf8'))
+  const incoming = runnerConfig(paths, root)
   let current = {}
   if (fs.existsSync(paths.configTarget)) {
     try { current = JSON.parse(fs.readFileSync(paths.configTarget, 'utf8')) } catch (error) {
@@ -341,31 +454,57 @@ function install(root, name, output = console) {
   }
   const items = [...(runner.instructions || []), ...(runner.artifacts || [])]
   const resolvedItems = items.map((item) => ({ item, ...resolveItem(paths, root, name, item) }))
-  F.assertNoSymlinkPath(root, paths.configTarget)
-  for (const resolved of resolvedItems) {
-    F.assertNoSymlinkPath(root, resolved.target)
-    if (fs.existsSync(resolved.target)
-      && !runner.instructions.includes(resolved.item)
-      && fs.readFileSync(resolved.target, 'utf8') !== fs.readFileSync(resolved.source, 'utf8')) {
-      throw new Error(`${resolved.item.target} existe y difiere de la fuente canónica`)
-    }
+  F.assertNoSymlinkPath(paths.install, paths.configTarget)
+  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)]))
+  // 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) => {
+    return state.get(resolved) === 'ajeno' && !runner.instructions.includes(resolved.item)
+  })
+  if (editados.length && !options.force) {
+    throw new Error(
+      `${editados.length} archivo(s) que mantiene Cauce fueron editados y se perderían:\n`
+      + `${editados.map((resolved) => `- ${resolved.item.target}`).join('\n')}\n\n`
+      + 'Son del toolkit: en vez de editarlos, agregá lo tuyo al lado y registralo en la\n'
+      + 'configuración de tu runner. Si el cambio ya no te sirve, repetí con --force.',
+    )
   }
   const merged = pruneSupersededHooks(mergeConfig(current, incoming))
   F.atomicWriteJson(paths.configTarget, merged.config)
   for (const { wrapper, files } of merged.replaced) {
     output.log(`− ${name}: reemplazado ${[...new Set(files)].join(', ')} por ${wrapper}`)
   }
+  // 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}: configuración instalada en ${runner.config.target}`)
+  const entregado = { ...recorded }
   for (const resolved of resolvedItems) {
-    if (fs.existsSync(resolved.target)) {
-      output.log(`= ${name}: conservado ${resolved.item.target}`)
+    const situacion = state.get(resolved)
+    const propio = runner.instructions.includes(resolved.item)
+    if (situacion === 'ajeno' && propio) {
+      output.log(`= ${name}: conservado ${resolved.item.target} (tiene cambios tuyos)`)
+    } else if (situacion === 'al día') {
+      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)
-      output.log(`✓ ${name}: instalado ${resolved.item.target}`)
+      const verbo = situacion === 'nuevo' ? 'instalado' : 'actualizado'
+      output.log(`✓ ${name}: ${verbo} ${resolved.item.target}`)
+    }
+    // Sólo se anota lo que Cauce puso: un archivo conservado con cambios de la empresa no es una
+    // entrega, y registrarlo lo volvería indistinguible de uno intacto en la próxima instalación.
+    if (!(situacion === 'ajeno' && propio)) {
+      entregado[deliveryKey(name, resolved.item.target)] = M.digest(resolved.target)
     }
   }
   installRoleSkills(root, runner, output)
+  M.write(root, undefined, entregado)
   return runner
 }
 

package/engine/cli/ops.js

@@ -140,20 +140,6 @@ function init(target) {
     preserve,
     root,
   )
-  copyRuntime(
-    path.join(PROJECT_ROOT, 'automatization', 'runners'),
-    path.join(root, 'automatization', 'runners'),
-    preserve,
-    root,
-    // El README de runners lo provee el template: le habla al proyecto, no a quien desarrolla Cauce.
-    O.TEMPLATE_OWNED.filter((owned) => owned.startsWith('automatization/runners/')).map((owned) => path.basename(owned)),
-  )
-  copyRuntime(
-    path.join(PROJECT_ROOT, 'automatization', 'workflows'),
-    path.join(root, 'automatization', 'workflows'),
-    preserve,
-    root,
-  )
   const version = require(path.join(PROJECT_ROOT, 'package.json')).version
   // Un repo con npm recibe el motor como dependencia versionada; uno de Go, Python o Rust recibe
   // la copia, porque exigirle un package.json para correr su planning sería imponerle un stack.
@@ -165,9 +151,18 @@ function init(target) {
     const engine = path.join(root, '.ops', 'engine')
     copyRuntime(path.join(PROJECT_ROOT, 'engine'), engine, preserve, root)
     fs.chmodSync(path.join(engine, 'cli', 'ops.js'), 0o755)
-    // Sin npm no hay de dónde leer el catálogo en tiempo de ejecución: viaja junto al motor.
+    // Sin npm no hay de dónde leer el catálogo en tiempo de ejecución: viaja junto al motor, igual
+    // que los adaptadores de runner y los workflows que instala `automation install`.
     copyRuntime(path.join(PROJECT_ROOT, 'agents'), path.join(root, '.ops', 'agents'), preserve, root)
     copyRuntime(path.join(PROJECT_ROOT, 'teams'), path.join(root, '.ops', 'teams'), preserve, root)
+    for (const name of ['runners', 'workflows']) {
+      copyRuntime(
+        path.join(PROJECT_ROOT, 'automatization', name),
+        path.join(root, '.ops', 'automatization', name),
+        preserve,
+        root,
+      )
+    }
   }
   let entregado = {}
   for (const relative of O.trackedPaths()) {
@@ -546,10 +541,7 @@ function upgrade(dir) {
     // `.ops/` es el paquete vendorizado de una instancia sin npm. Si no existe, esta instancia lo
     // toma de la dependencia y crearlo sería duplicar lo que el lockfile ya versiona.
     if (relative.startsWith('.ops/') && !fs.existsSync(target)) continue
-    const skip = O.TEMPLATE_OWNED
-      .filter((owned) => owned.startsWith(`${relative}/`))
-      .map((owned) => path.basename(owned))
-    if (fs.statSync(origin).isDirectory()) overlayTree(origin, target, root, skip)
+    if (fs.statSync(origin).isDirectory()) overlayTree(origin, target, root)
     else {
       F.assertNoSymlinkPath(root, target)
       F.atomicWrite(target, fs.readFileSync(origin, 'utf8'))
@@ -573,7 +565,7 @@ function upgrade(dir) {
     const dir = path.join(root, relative)
     if (fs.existsSync(dir)) registro = { ...registro, ...M.record(root, relative, O.treeFiles(dir)) }
   }
-  M.write(root, registro)
+  M.write(root, M.prune(root, registro))
 
   const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   config.cauceVersion = to
@@ -590,6 +582,14 @@ function upgrade(dir) {
     console.log(`= conservado ${override.collection}/${override.project}: sobrescribe ${override.system}`)
   }
   console.log('  planning, organization y todo lo propio quedaron intactos')
+  // El wiring del runner no se actualiza solo: vive fuera de la instancia y lo escribe otro comando.
+  // Sin este recordatorio, una mejora en un workflow o en el catálogo se queda en el paquete.
+  const runners = Object.keys(M.readRunners(root))
+    .map((key) => key.split('/')[0])
+    .filter((name, index, all) => all.indexOf(name) === index)
+  for (const name of runners) {
+    console.log(`  reinstalá tu runner para que el wiring quede al día: make install-${name}`)
+  }
 }
 
 // Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
@@ -717,7 +717,8 @@ function automation(action, rootArg, runnerName) {
   }
   if (action === 'install') {
     let runner
-    try { runner = A.install(root, runnerName) } catch (error) { fail(error.message, 2) }
+    const force = process.argv.includes('--force')
+    try { runner = A.install(root, runnerName, console, { force }) } catch (error) { fail(error.message, 2) }
     if (runnerName === 'codex') {
       console.log('  Codex pedirá revisar y confiar en hooks nuevos al iniciar sesión.')
     }

package/engine/core/manifest.js

@@ -19,18 +19,38 @@ function digest(file) {
   } catch { return '' }
 }
 
-function read(root) {
+// Dos secciones porque son dos entregas distintas: `files` es lo que se materializó dentro de la
+// instancia y `runners` lo que un adaptador dejó fuera de ella —en modo sidecar el wiring vive en
+// la carpeta de la compañía—. El registro se queda igual acá, que es el repo que la empresa versiona.
+function readAll(root) {
   try {
-    const data = JSON.parse(fs.readFileSync(path.join(root, FILE), 'utf8'))
-    return data && typeof data.files === 'object' ? data.files : {}
-  } catch { return {} }
+    const data = JSON.parse(fs.readFileSync(path.join(root, FILE), 'utf8')) || {}
+    return {
+      files: typeof data.files === 'object' && data.files ? data.files : {},
+      runners: typeof data.runners === 'object' && data.runners ? data.runners : {},
+    }
+  } catch { return { files: {}, runners: {} } }
 }
 
-function write(root, files) {
+function read(root) { return readAll(root).files }
+
+function readRunners(root) { return readAll(root).runners }
+
+// Cada sección que no se pasa se conserva: `upgrade` no sabe del wiring y `install` no sabe de la
+// instancia, y ninguno de los dos debería borrar lo que el otro anotó.
+function write(root, files, runners) {
+  const current = readAll(root)
   const target = path.join(root, FILE)
   fs.mkdirSync(path.dirname(target), { recursive: true })
-  const ordered = Object.fromEntries(Object.entries(files).sort(([left], [right]) => left.localeCompare(right)))
-  fs.writeFileSync(target, `${JSON.stringify({ version: 1, files: ordered }, null, 2)}\n`)
+  const ordered = (map) => Object.fromEntries(
+    Object.entries(map).sort(([left], [right]) => left.localeCompare(right)),
+  )
+  const data = {
+    version: 1,
+    files: ordered(files || current.files),
+    runners: ordered(runners || current.runners),
+  }
+  fs.writeFileSync(target, `${JSON.stringify(data, null, 2)}\n`)
 }
 
 // Registra lo entregado en una ruta, relativo a la raíz de la instancia.
@@ -40,6 +60,15 @@ function record(root, relative, files) {
   return current
 }
 
+// Olvida lo que ya no está en disco. Sin esto el registro sólo crece: una ruta retirada deja su
+// digest para siempre, y el día que un nombre se reutilice la entrega nueva se leería como una
+// edición local y detendría la actualización.
+function prune(root, files) {
+  return Object.fromEntries(
+    Object.entries(files).filter(([file]) => fs.existsSync(path.join(root, file))),
+  )
+}
+
 // Archivos que la empresa modificó después de recibirlos. Un archivo sin registro previo no
 // cuenta: llegó con una versión anterior a este mecanismo, o lo agregó el proyecto.
 function edited(root, relative, files) {
@@ -51,4 +80,4 @@ function edited(root, relative, files) {
   })
 }
 
-module.exports = { FILE, digest, edited, read, record, write }
+module.exports = { FILE, digest, edited, prune, read, readRunners, record, write }

package/engine/core/ownership.js

@@ -25,6 +25,8 @@ const SYSTEM_FILES = [
   'organization/roles/README.md',
   'teams/000-template.md',
   'teams/README.md',
+  'automatization/README.md',
+  'automatization/AGENTS.md',
 ]
 
 // Colecciones mixtas: el toolkit posee `<dir>/system/`, el proyecto todo lo demás del directorio.
@@ -41,23 +43,27 @@ const RUNTIME_PATHS = [
   '.ops/engine',
   '.ops/agents',
   '.ops/teams',
+  '.ops/automatization/runners',
+  '.ops/automatization/workflows',
   'automatization/hooks',
-  'automatization/runners',
-  'automatization/workflows',
 ]
 
-// Rutas que el paquete tiene por duplicado: una versión para el proyecto en `template/` y otra
-// interna del toolkit. Gana la del template, que es la que le habla a quien usa la instancia.
-const TEMPLATE_OWNED = ['automatization/runners/README.md']
-
 // Dentro del paquete, lo que una instancia recibe en su raíz vive bajo `template/`; el catálogo,
 // los equipos y la automatización están en la raíz del paquete, y el motor en `engine/`.
-const TEMPLATE_PREFIXES = ['planning/', 'organization/', 'integrations/', 'teams/']
+const TEMPLATE_PREFIXES = [
+  'planning/',
+  'organization/',
+  'integrations/',
+  'teams/',
+  'automatization/',
+]
 
 function sourceOf(relative) {
-  if (relative === '.ops/engine') return 'engine'
-  if (relative === '.ops/agents') return 'agents'
-  if (relative === '.ops/teams') return 'teams'
+  // `.ops/` es el paquete vendorizado: cada ruta de ahí adentro se llama igual en el origen.
+  if (relative.startsWith('.ops/')) return relative.slice('.ops/'.length)
+  // El runtime sale de la raíz del paquete aunque su prefijo sea de plantilla: `automatization/`
+  // le entrega documentos a la instancia, pero los guards que ejecuta son los del toolkit.
+  if (RUNTIME_PATHS.includes(relative)) return relative
   if (TEMPLATE_PREFIXES.some((prefix) => relative.startsWith(prefix))) {
     return path.join('template', relative)
   }
@@ -81,6 +87,17 @@ function engineAt(root, relative = '') {
     .find((candidate) => fs.existsSync(candidate)) || ''
 }
 
+// Una ruta cualquiera del paquete, en el mismo orden de preferencia que el motor. La usan los
+// adaptadores de runner y los workflows: el motor los consume, el proyecto no los materializa.
+function packagePath(root, relative) {
+  const candidates = [
+    path.join(root, 'node_modules', '@ingeniomaps', 'cauce', relative),
+    path.join(root, '.ops', relative),
+    path.join(root, relative),
+  ]
+  return candidates.find((candidate) => fs.existsSync(candidate)) || ''
+}
+
 // Definiciones que consume el motor —cargos y equipos— y que por eso viajan con el paquete en vez
 // 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.
@@ -135,6 +152,8 @@ const RETIRED = [
   'agents/roles/system',
   'teams/system',
   '.github/workflows/agent-learning.yml',
+  'automatization/runners',
+  'automatization/workflows',
 ]
 
 // Aprendizaje que quedó dentro de una ruta retirada. Es lo único ahí que no se puede reponer, así
@@ -205,7 +224,7 @@ module.exports = {
   retiredWithLearning,
   engineAt,
   engineCandidates,
-  TEMPLATE_OWNED,
+  packagePath,
   SYSTEM_COLLECTIONS,
   SYSTEM_FILES,
   identity,

package/package.json

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

package/template/AGENTS.md

@@ -58,8 +58,9 @@ Aplica a `planning/business-rules/`, `planning/adr/`, `planning/rules/`, `teams/
 `planning/` —roadmap, backlog, WIP, done, inbox y acciones humanas— es del proyecto y no se toca al
 actualizar.
 
-`automatization/hooks/` y `automatization/runners/` son runtime del toolkit y se reemplazan enteros. No
-tienen `system/` porque no hace falta: lo que un proyecto necesita ya funciona sin editarlos.
+`automatization/hooks/` es runtime del toolkit y se reemplaza entero. No tiene `system/` porque no hace
+falta: lo que un proyecto necesita ya funciona sin editarlo. Los adaptadores de runner y los workflows ni
+siquiera están acá — los lee el motor desde el paquete.
 
 - **Agregar un guard propio**: creá `automatization/hooks/guard-<nombre>.sh` y registralo en la
   configuración de tu runner. Sobrevive a cada actualización, porque el toolkit no lo conoce.

package/template/automatization/README.md

@@ -1,19 +1,34 @@
-# Automatización de {{PROJECT_NAME}}
+# Automatización
 
 Wiring local entre `planning/PROTOCOL.md` y el runner elegido. El proyecto empieza en modo manual y seguro;
-activar un runner requiere completar su adaptador bajo `runners/`.
+ningún runner se activa solo.
 
 - `config.json`: runner activo y gates requeridos.
-- `hooks/`: implementaciones específicas del runner.
-- `workflows/`: recorridos específicos del runner.
-- `runners/`: instalación y configuración por herramienta.
+- `hooks/`: los guards que se ejecutan. Acá va también el tuyo: agregalo con otro nombre y registralo
+  en la configuración de tu runner, que es del proyecto y sobrevive a cada actualización.
+
+Los adaptadores de runner y los workflows no se copian acá: son definiciones que el motor consume y
+viajan con Cauce, igual que el catálogo de cargos y los equipos. `automation install` los lee desde ahí.
 
 No copies reglas del protocolo aquí: enlázalas y mecaniza únicamente lo comprobable.
 
 ```bash
 node tools/ops.js automation check .
-node tools/ops.js automation install . codex
+node tools/ops.js automation install . claude
+```
+
+**Dónde aterriza**: en modo `embedded`, acá mismo. En modo `sidecar` el runner se instala en la carpeta
+de la compañía —la que contiene este repo y los de producto—, porque es donde el dev abre la
+herramienta y la única desde la que ve el código. El comando dice la ruta exacta al terminar.
+
+Hay adaptadores para Claude, Codex, Antigravity y Gemini. Antigravity (`agy`) es la opción Google
+recomendada para cuentas individuales y proyectos nuevos; Gemini se conserva para Enterprise, Google
+Cloud y API keys. La instalación conserva la configuración existente, y `doctor` comprueba archivos y
+disponibilidad del CLI sin autenticarse.
+
+```bash
+make install-antigravity
+make doctor-antigravity
 ```
 
-También puede usarse `make install-claude`, `make install-codex` o `make install-gemini`.
-Valida después con `make doctor-claude`, `make doctor-codex` o `make doctor-gemini`.
+También existen `make install-claude`, `make install-codex` y `make install-gemini`, con sus `doctor-*`.

package/template/automatization/runners/README.md

@@ -1,13 +0,0 @@
-# Runners
-
-Esta instancia incluye adaptadores instalables para Claude, Codex, Antigravity y Gemini, pero ninguno se
-activa automáticamente. Antigravity (`agy`) es la opción Google recomendada para cuentas individuales y
-proyectos nuevos. Gemini se conserva para Enterprise, Google Cloud y API keys.
-
-```bash
-make install-antigravity
-make doctor-antigravity
-```
-
-Usa el alias equivalente para otro runner. La instalación conserva configuración existente y `doctor`
-comprueba archivos y disponibilidad del CLI sin autenticarse.

package/template/automatization/workflows/.gitkeep

@@ -1 +0,0 @@
-