@ingeniomaps/cauce 0.54.0 → 0.56.0

package/CHANGELOG.md

@@ -14,6 +14,67 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
 diseño — eso vive en el commit y en el código.
 
+## [0.56.0] - 2026-09-03
+
+### Corregido
+
+- **El upgrade que documentaba el README rompía el pin exacto que puso `init`.** La razón para no
+  saltear su primer paso es que «`init` fija la versión exacta, así que `npm update` no la mueve», y
+  el comando de al lado la desarmaba: npm guarda con caret por defecto, así que
+  `npm install --save-dev @ingeniomaps/cauce@latest` dejaba `^0.55.0`, y dentro de `0.x` ese caret
+  alcanza a los patches —que Cauce publica—. Un `npm install` en otra máquina podía dejar el motor en
+  una versión que `ops.config.json` no decía.
+
+  Se arregla por los dos lados. El comando lleva `--save-exact` en los tres lugares que lo dictan —el
+  README, el `make upgrade` de tu instancia y la salida de `upgrade --check`—, y además **`upgrade`
+  repone la versión exacta al terminar**, así que una instancia que ya quedó con un rango se repara
+  sola en la próxima actualización. **Qué cambia para vos**: `upgrade` puede tocar ahora una línea de
+  tu `package.json`, y lo dice cuando lo hace. El resto del manifiesto queda como estaba, y una
+  instancia sin `package.json` no recibe uno.
+
+## [0.55.0] - 2026-09-02
+
+### Corregido
+
+- **`upgrade` ya no pisa lo que `init --force` conservó.** Adoptar Cauce en un repositorio que ya tiene
+  contenido es `init --force` y después `upgrade`. El primero conserva tus archivos y lo cumple; el
+  segundo los reemplazaba sin avisar e imprimía que no había tocado nada propio. El registro se grababa
+  hasheando el disco, así que un archivo conservado quedaba anotado como entregado por Cauce con **tu**
+  contenido, y la comparación no veía ninguna diferencia. Ahora se anota el digest de lo que el molde
+  habría escrito: tu archivo se ve como lo que es —una edición local— y `upgrade` se detiene
+  nombrándolo. **Qué cambia para vos**: el primer `upgrade` después de una adopción con `--force` se
+  detiene listando esos archivos. Resolvelos a mano, o repetí con `--force` para descartarlos, que
+  ahora además los enumera en la salida.
+- **Tu guard propio sobrevive a `automation install`.** `AGENTS.md` te dice que lo pongas en
+  `automatization/hooks/guard-<nombre>.sh` y promete que sobrevive a cada actualización. Sobrevivía al
+  `upgrade` y no a la reinstalación del runner: lo nuestro se reconocía por la carpeta, así que
+  cualquier `guard-*.sh` de ahí se desregistraba antes de fusionar. El archivo quedaba en disco, el
+  guard dejaba de correr y lo único que se veía era una línea diciendo que se había quitado una entrada
+  obsoleta. Ahora se reconoce por lo que efectivamente entregamos: los guards que el motor trae, más
+  los que esta instancia anotó haber recibido —el manifiesto gana una entrada por runner con el wiring
+  que dejó puesto, y por eso una entrada nuestra se sigue retirando el día que el motor deje de traer
+  ese guard—. **Si moviste tu guard fuera de esa carpeta para sortearlo, ya podés devolverlo.**
+- **`automation doctor` deja de llamar divergente a una configuración completa.** Un hook propio sumado
+  *dentro* de un grupo que escribió el toolkit dejaba a `doctor` en rojo aunque estuvieran todas las
+  entradas esperadas: comparaba el grupo entero serializado, así que uno con un hook de más contaba
+  como ausente. Ahora compara por `matcher` y contenido. Lo que falta se sigue reportando igual.
+- **`upgrade --check` avisa de lo que tenés editado aunque la versión coincida.** Salía por un camino
+  corto que informaba «al día» sin llegar a listarlo, que es el estado normal entre actualizaciones
+  —`init` fija la versión exacta—: el único modo que no toca nada era también el único que no podía
+  anticipar el conflicto. **Qué cambia para vos**: `--check` ahora sale 1 cuando hay archivos del
+  sistema editados, un caso donde antes salía 0. Si lo tenés en un script, revisá esa condición.
+
+### Cambiado
+
+- **`init` e `init .` eligen el mismo modo en el mismo directorio.** El default salía de si escribiste
+  el argumento, no de a dónde apunta: en `acme-ops/`, `init` daba `sidecar` e `init .` daba `embedded`.
+  No es cosmético — en `embedded` la raíz del workspace pasa a ser la carpeta ops misma, así que
+  `guard-workspace-boundary` deja de reconocer los repos hermanos y el wiring del runner se escribe
+  adentro en vez de al lado, donde abrís tu herramienta. Ahora lo decide el destino resuelto, con la
+  misma regla que ya elegía dónde aterrizar: una carpeta llamada `ops` o terminada en `-ops` **es** la
+  instancia. **Qué cambia para vos**: `init .` en una carpeta así ahora da `sidecar`, donde antes daba
+  `embedded`. El caso embebido sigue disponible pidiéndolo: `init . --mode embedded`.
+
 ## [0.54.0] - 2026-09-02
 
 ### Agregado

package/README.md

@@ -266,13 +266,15 @@ existente detiene el `upgrade` antes de pisarlo.
 Son tres pasos y `make upgrade` hace los dos primeros:
 
 ```bash
-npm install --save-dev @ingeniomaps/cauce@latest   # trae el motor nuevo
+npm install --save-exact --save-dev @ingeniomaps/cauce@latest   # trae el motor nuevo
 node tools/ops.js upgrade .                        # aplica system/ y el runtime
 node tools/ops.js automation install . claude      # el wiring del runner
 ```
 
 El primero no se puede saltear: `init` fija la versión exacta, así que `npm update` no la mueve y
-`upgrade` compara contra el motor instalado —lo dice en su salida—. El tercero tampoco: los workflows y
+`upgrade` compara contra el motor instalado —lo dice en su salida—. Va con `--save-exact` porque npm
+guarda con caret por defecto, y ese caret es justamente lo que volvería falsa la frase anterior; si
+alguna vez se instaló sin él, `upgrade` repone la versión exacta al terminar. El tercero tampoco: los workflows y
 las skills viven en el runner, no en la instancia, y `upgrade` no los toca. `upgrade` lo recuerda al
 terminar.
 

package/engine/automation/config.js

@@ -8,7 +8,7 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const F = require('../core/files')
-const { supersededGuards } = require('./hooks')
+const { supersededGuards, expectedHooks } = require('./hooks')
 
 function mergeConfig(current, incoming) {
   if (Array.isArray(incoming)) {
@@ -32,19 +32,40 @@ function mergeConfig(current, incoming) {
   return incoming
 }
 
-// Una entrada de hook que puso Cauce se reconoce por el guard al que apunta: `automatization/hooks/`
-// es nuestro y ninguna empresa escribe ahí. Se saca del archivo del usuario antes de fusionar para que
-// el merge deje exactamente las de esta versión, ni una más.
-const DELIVERED = /automatization\/hooks\/guard-[a-z-]+\.sh/
+// Una entrada de hook que puso Cauce se reconoce por el guard al que apunta, y lo nuestro es lo que
+// efectivamente entregamos, no todo lo que vive en nuestra carpeta. Reconocer por directorio
+// desregistraba el guard propio del proyecto en cada reinstalación: `template/AGENTS.md` invita a
+// ponerlo justo ahí y promete que sobrevive a cada actualización, el archivo quedaba en disco, y lo
+// único que se veía era una línea diciendo que se había quitado una entrada obsoleta.
+// Se saca del archivo del usuario antes de fusionar para que el merge deje exactamente las de esta
+// versión, ni una más.
+const HOOK_PATH = /automatization\/hooks\/([a-z0-9-]+\.sh)(?:\s|$)/
 
-function withoutDeliveredHooks(config, live) {
+// Dos fuentes, y la segunda es la que cierra el borde. `expectedHooks()` dice qué entrega el motor de
+// hoy y alcanza para una instancia que nunca instaló; `delivered` es lo que esta instancia registró
+// haber recibido la última vez, y es lo único que reconoce un guard que entregamos en una versión y
+// retiramos en la siguiente: su nombre ya no está en la lista de hoy, así que sin el registro quedaría
+// vivo en la configuración llamando a un guard que Cauce ya no mantiene. Un guard propio del proyecto
+// no está en ninguna de las dos, que es exactamente por lo que sobrevive.
+function isDelivered(command, delivered) {
+  const hit = String(command).match(HOOK_PATH)
+  if (!hit) return false
+  return expectedHooks().includes(hit[1]) || delivered.has(String(command))
+}
+
+// Lo que de un conjunto de comandos es wiring de guards nuestro, para anotarlo como entregado.
+function deliveredHookCommands(commands) {
+  return [...commands].filter((command) => HOOK_PATH.test(String(command)))
+}
+
+function withoutDeliveredHooks(config, live, delivered = new Set()) {
   const dropped = []
   const walk = (node) => {
     if (Array.isArray(node)) {
       return node
         .filter((item) => {
           const command = item && typeof item === 'object' ? String(item.command || '') : ''
-          if (!DELIVERED.test(command)) return true
+          if (!isDelivered(command, delivered)) return true
           // Sólo se anuncia lo que ya no vuelve: una entrada que el merge repone quedó igual, y decir
           // que se quitó y se puso la misma línea es ruido que esconde el caso que sí importa.
           if (!live.has(command)) dropped.push(command)
@@ -83,9 +104,20 @@ function reportRemoved(name, dropped, live, output) {
 
 function includesConfig(actual, expected) {
   if (Array.isArray(expected)) {
-    return Array.isArray(actual) && expected.every((item) => {
-      return actual.some((value) => JSON.stringify(value) === JSON.stringify(item))
-    })
+    return Array.isArray(actual) && expected.every((item) => actual.some((value) => {
+      // Un grupo de hooks se compara por su contenido, no por su forma serializada. La comprobación es
+      // «contiene», que es lo correcto, pero con el ítem entero como unidad un grupo `{matcher, hooks}`
+      // con un hook de más dejaba de ser el mismo objeto y contaba como ausente: `doctor` llamaba
+      // divergente a una configuración que tenía todo lo esperado, y el anidamiento —donde vive la
+      // diferencia real— no se miraba nunca. La instalación promete conservar lo que el proyecto ya
+      // tenía, así que sumar un hook propio a un grupo nuestro es exactamente lo que permite.
+      if (item && typeof item === 'object' && Array.isArray(item.hooks)) {
+        return value && typeof value === 'object'
+          && value.matcher === item.matcher
+          && includesConfig(value.hooks, item.hooks)
+      }
+      return JSON.stringify(value) === JSON.stringify(item)
+    }))
   }
   if (expected && typeof expected === 'object') {
     return actual && typeof actual === 'object' && Object.entries(expected).every(([key, value]) => {
@@ -170,6 +202,6 @@ function blockUpToDate(file, name, content) {
 
 module.exports = {
   blockStart,
-  mergeConfig, withoutDeliveredHooks, reportRemoved, includesConfig, hasHooks,
+  mergeConfig, withoutDeliveredHooks, deliveredHookCommands, reportRemoved, includesConfig, hasHooks,
   unmergeConfig, isSharedFile, withoutBlock, mergeInstruction, blockUpToDate,
 }

package/engine/automation/index.js

@@ -17,7 +17,7 @@ const {
   legacyGuardWiring, staleHooks, listHooks,
 } = require('./hooks')
 const {
-  blockStart, mergeConfig, withoutDeliveredHooks, reportRemoved, includesConfig, hasHooks,
+  blockStart, mergeConfig, withoutDeliveredHooks, deliveredHookCommands, reportRemoved, includesConfig, hasHooks,
   unmergeConfig, isSharedFile, withoutBlock, mergeInstruction, blockUpToDate,
 } = require('./config')
 
@@ -226,6 +226,11 @@ function deliveryKey(name, target) {
   return `${name}/${target.split(path.sep).join('/')}`
 }
 
+// La sección `runners` del manifiesto anota archivo → digest; ésta es la única entrada que guarda una
+// lista, porque lo que registra no es un archivo sino las entradas que dejamos dentro del archivo de
+// configuración del usuario. No colisiona con ningún `target`: ninguno se llama así.
+const HOOKS_KEY = 'config.hooks'
+
 // En qué estado quedó un archivo que este adaptador entregó alguna vez.
 //
 //   nuevo          no existe todavía
@@ -277,6 +282,7 @@ function uninstall(root, name, output = console) {
 
   const items = [...(runner.instructions || []), ...(runner.artifacts || [])]
   const deliveredPaths = { ...recorded }
+  delete deliveredPaths[deliveryKey(name, HOOKS_KEY)]
   for (const item of items) {
     const resolved = { item, ...resolveItem(paths, root, name, item) }
     const key = deliveryKey(name, item.target)
@@ -378,7 +384,12 @@ function install(root, name, output = console, options = {}) {
   // guard que el runner intenta ejecutar y falla. Se quitan las nuestras y las vuelve a poner el merge.
   const live = new Set((JSON.stringify(incoming).match(/"command":"[^"]*"/g) || [])
     .map((entry) => JSON.parse(`{${entry}}`).command))
-  const clean = runner.config.owned ? { config: {}, dropped: [] } : withoutDeliveredHooks(current, live)
+  // Lo que este adaptador anotó haber entregado la última vez. Es lo único que reconoce una entrada
+  // nuestra cuyo guard el motor ya no trae: por nombre no se distingue de la que agregó el proyecto.
+  const previous = new Set(recorded[deliveryKey(name, HOOKS_KEY)] || [])
+  const clean = runner.config.owned
+    ? { config: {}, dropped: [] }
+    : withoutDeliveredHooks(current, live, previous)
   reportRemoved(name, clean.dropped, live, output)
   F.atomicWriteJson(paths.configTarget, mergeConfig(clean.config, incoming))
   // Dónde aterrizó, no sólo qué archivo: en sidecar el destino no es el repo desde el que se corrió
@@ -388,6 +399,12 @@ function install(root, name, output = console, options = {}) {
   }
   output.log(`✓ ${name}: configuración instalada en ${runner.config.target}`)
   const deliveredPaths = { ...recorded }
+  // Qué wiring de guards dejamos puesto, para poder retirarlo el día que el motor deje de traerlo. Se
+  // anota lo que instalamos y no lo que quedó en el archivo: ahí conviven las entradas del proyecto, y
+  // registrarlas nos autorizaría a borrar lo ajeno en la instalación siguiente.
+  const ourHooks = deliveredHookCommands(live)
+  if (ourHooks.length) deliveredPaths[deliveryKey(name, HOOKS_KEY)] = ourHooks
+  else delete deliveredPaths[deliveryKey(name, HOOKS_KEY)]
   for (const resolved of resolvedItems) {
     const status = state.get(resolved)
     const ownFile = runner.instructions.includes(resolved.item)

package/engine/cli/dependency.js

@@ -0,0 +1,73 @@
+'use strict'
+
+// Cómo una instancia declara el motor en su `package.json`: ponerlo, reponerlo y sacarlo. Vive aparte
+// del ciclo de vida porque su reloj es otro —npm y el versionado, no crear/actualizar/borrar— y porque
+// sus tres consumidores no se solapan: `scaffold` declara, `upgrade` repone y `destroy` saca.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const F = require('../core/files')
+const { fail } = require('./io')
+
+// Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
+// Conserva el manifiesto existente porque el repo anfitrión puede tener el suyo.
+function declareEngine(manifest, version) {
+  let pkg = { name: path.basename(path.dirname(manifest)), private: true, version: '0.0.0' }
+  if (fs.existsSync(manifest)) {
+    try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch (error) {
+      fail(`package.json inválido en ${manifest}: ${error.message}`)
+    }
+  }
+  pkg.devDependencies = { ...pkg.devDependencies, '@ingeniomaps/cauce': version }
+  F.atomicWriteJson(manifest, pkg)
+}
+
+// Repone la versión exacta que `declareEngine` había dejado, y devuelve la que había si cambió algo.
+//
+// El pin no sobrevive por sí solo: npm guarda con caret, así que el `npm install @latest` del primer
+// paso del upgrade lo convierte en un rango, y con eso deja de valer la razón que el README da para no
+// saltear ese paso —«init fija la versión exacta, así que npm update no la mueve»—. Repararlo acá y no
+// sólo documentar el comando es lo que vuelve la propiedad independiente de cómo se haya instalado.
+//
+// Sin manifiesto no hay nada que reponer: una instancia que no lo tiene resuelve el motor de otra
+// forma, y crearle uno sería otra operación que nadie pidió en un upgrade.
+function pinEngine(root, version) {
+  const manifest = path.join(root, 'package.json')
+  if (!fs.existsSync(manifest)) return null
+  let pkg
+  try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch { return 'ilegible' }
+  const current = (pkg.devDependencies || {})['@ingeniomaps/cauce']
+  if (!current || current === version) return null
+  declareEngine(manifest, version)
+  return current
+}
+
+// La inversa exacta de `declareEngine`: saca la clave que puso y nada más. El resto del manifiesto es
+// del repo anfitrión aunque hoy no tenga otra cosa —un `package.json` vacío puede ser lo que alguien
+// escribió para tener scripts— así que el archivo se borra sólo si es idéntico al que `declareEngine`
+// habría creado desde cero, sin dependencias, sin scripts y con su `version: 0.0.0`.
+//
+// Lo que no se toca nunca es `node_modules/` ni el lockfile: los escribe npm, pueden tener dependencias
+// del proyecto y borrarlos por nuestra cuenta destruye trabajo ajeno. Se nombran en la salida, que es
+// la mitad que faltaba: `destroy` decía «tu repositorio queda donde está» y dejaba un `package.json`
+// cuya única dependencia era Cauce. En un repo Rust eso es basura conspicua y nadie avisaba.
+function undeclareEngine(manifest) {
+  if (!fs.existsSync(manifest)) return []
+  let pkg
+  try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch { return [] }
+  const dev = pkg.devDependencies || {}
+  if (!('@ingeniomaps/cauce' in dev)) return []
+  delete dev['@ingeniomaps/cauce']
+  pkg.devDependencies = dev
+  const ours = !Object.keys(dev).length && !Object.keys(pkg.dependencies || {}).length
+    && !Object.keys(pkg.scripts || {}).length && pkg.private === true && pkg.version === '0.0.0'
+  if (ours) {
+    fs.rmSync(manifest, { force: true })
+    return ['package.json (lo había creado init: sin dependencias ni scripts propios)']
+  }
+  if (!Object.keys(dev).length) delete pkg.devDependencies
+  F.atomicWriteJson(manifest, pkg)
+  return ['package.json: se quitó la dependencia del motor y el resto queda como estaba']
+}
+
+module.exports = { declareEngine, pinEngine, undeclareEngine }

package/engine/cli/instance.js

@@ -16,6 +16,7 @@ const P = require('../planning/parser')
 const ST = require('../planning/state')
 const A = require('../automation')
 const { fail } = require('./io')
+const { declareEngine, pinEngine, undeclareEngine } = require('./dependency')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
@@ -29,9 +30,14 @@ function providerNames() {
   } catch { return [] }
 }
 
+// Devuelve, por archivo conservado, el digest de lo que el molde **habría** escrito. Adoptar Cauce en
+// un repositorio con contenido es `init --force`, y lo que se conserva ahí lo escribió la empresa: si
+// el manifiesto lo registra hasheando el disco queda declarado como entregado por Cauce con contenido
+// que Cauce nunca entregó, y el `upgrade` siguiente no ve ninguna edición local y lo reemplaza.
 function copyTemplate(source, target, replacements, force, skip = [], quiet = false) {
   F.assertNoSymlinkPath(path.dirname(target), target)
   fs.mkdirSync(target, { recursive: true })
+  const preserved = {}
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
@@ -39,11 +45,14 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
     // 11.16.0: lo deja afuera en la raíz y en subdirectorios—, así que viaja sin punto y se restituye
     // acá. Sin esto el archivo existe en el repo del toolkit y desaparece para todo consumidor real.
     const to = path.join(target, entry.name === 'gitignore' ? '.gitignore' : entry.name)
-    if (entry.isDirectory()) copyTemplate(from, to, replacements, force, skip, quiet)
+    if (entry.isDirectory()) Object.assign(preserved, copyTemplate(from, to, replacements, force, skip, quiet))
     else {
       if (fs.existsSync(to)) {
         if (!force) fail(`El destino contiene ${to}. Usa un directorio vacío o --force.`)
         if (!quiet) console.log(`= conservado ${to}`)
+        let would = fs.readFileSync(from, 'utf8')
+        for (const [key, value] of Object.entries(replacements)) would = would.replaceAll(key, value)
+        preserved[to] = M.digestText(would)
         continue
       }
       let content = fs.readFileSync(from, 'utf8')
@@ -53,70 +62,36 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
       if (!quiet) console.log(`+ ${to}`)
     }
   }
+  return preserved
 }
 
+// Devuelve lo conservado igual que `copyTemplate`, y por la misma razón: acá el runtime no lleva
+// reemplazos, así que lo que habríamos escrito es el archivo del paquete tal cual.
 function copyRuntime(source, target, preserve = false, boundary = target, skip = []) {
   F.assertNoSymlinkPath(boundary, target)
   fs.mkdirSync(target, { recursive: true })
+  const preserved = {}
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
     const to = path.join(target, entry.name)
-    if (entry.isDirectory()) copyRuntime(from, to, preserve, boundary, skip)
-    else if (preserve && fs.existsSync(to)) console.log(`= conservado ${to}`)
-    else {
+    if (entry.isDirectory()) Object.assign(preserved, copyRuntime(from, to, preserve, boundary, skip))
+    else if (preserve && fs.existsSync(to)) {
+      console.log(`= conservado ${to}`)
+      preserved[to] = M.digest(from)
+    } else {
       F.assertNoSymlinkPath(boundary, to)
       fs.copyFileSync(from, to)
     }
   }
-}
-
-// Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
-// Conserva el manifiesto existente porque el repo anfitrión puede tener el suyo.
-function declareEngine(manifest, version) {
-  let pkg = { name: path.basename(path.dirname(manifest)), private: true, version: '0.0.0' }
-  if (fs.existsSync(manifest)) {
-    try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch (error) {
-      fail(`package.json inválido en ${manifest}: ${error.message}`)
-    }
-  }
-  pkg.devDependencies = { ...pkg.devDependencies, '@ingeniomaps/cauce': version }
-  F.atomicWriteJson(manifest, pkg)
-}
-
-// La inversa exacta de `declareEngine`: saca la clave que puso y nada más. El resto del manifiesto es
-// del repo anfitrión aunque hoy no tenga otra cosa —un `package.json` vacío puede ser lo que alguien
-// escribió para tener scripts— así que el archivo se borra sólo si es idéntico al que `declareEngine`
-// habría creado desde cero, sin dependencias, sin scripts y con su `version: 0.0.0`.
-//
-// Lo que no se toca nunca es `node_modules/` ni el lockfile: los escribe npm, pueden tener dependencias
-// del proyecto y borrarlos por nuestra cuenta destruye trabajo ajeno. Se nombran en la salida, que es
-// la mitad que faltaba: `destroy` decía «tu repositorio queda donde está» y dejaba un `package.json`
-// cuya única dependencia era Cauce. En un repo Rust eso es basura conspicua y nadie avisaba.
-function undeclareEngine(manifest) {
-  if (!fs.existsSync(manifest)) return []
-  let pkg
-  try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch { return [] }
-  const dev = pkg.devDependencies || {}
-  if (!('@ingeniomaps/cauce' in dev)) return []
-  delete dev['@ingeniomaps/cauce']
-  pkg.devDependencies = dev
-  const ours = !Object.keys(dev).length && !Object.keys(pkg.dependencies || {}).length
-    && !Object.keys(pkg.scripts || {}).length && pkg.private === true && pkg.version === '0.0.0'
-  if (ours) {
-    fs.rmSync(manifest, { force: true })
-    return ['package.json (lo había creado init: sin dependencias ni scripts propios)']
-  }
-  if (!Object.keys(dev).length) delete pkg.devDependencies
-  F.atomicWriteJson(manifest, pkg)
-  return ['package.json: se quitó la dependencia del motor y el resto queda como estaba']
+  return preserved
 }
 
 // El andamiaje de una instancia, sin leer argv. `init` es la cáscara que traduce banderas a esto, y
 // el banco de evaluación lo llama directo: crear una instancia programáticamente no puede depender de
 // cómo venga escrita la línea de comandos.
 function scaffold(root, { name, mode, force = false, quiet = false }) {
-  copyTemplate(path.join(PROJECT_ROOT, 'template'), root, {
+  const preserved = copyTemplate(path.join(PROJECT_ROOT, 'template'), root, {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
@@ -124,12 +99,12 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
   // No se copia `.github/`: `ci.yml` valida el toolkit con `npm run ci` —que una instancia no tiene— y
   // el ciclo de aprendizaje dejó de distribuirse en 0.4.0. Copiar salteando lo que no aplica dejaba
   // `.github/workflows/` vacío en cada instancia.
-  copyRuntime(
+  Object.assign(preserved, copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'hooks'),
     path.join(root, 'automatization', 'hooks'),
     force,
     root,
-  )
+  ))
   const version = require(path.join(PROJECT_ROOT, 'package.json')).version
   // El motor llega como dependencia para que el lockfile fije su versión. El repo ops es un sidecar:
   // declarar npm acá no convierte en Node al servicio de Go de al lado.
@@ -140,6 +115,14 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
     if (fs.existsSync(dir)) deliveredPaths = M.record(root, relative, O.treeFiles(dir), deliveredPaths)
   }
   deliveredPaths = M.recordPaths(root, O.SYSTEM_FILES, deliveredPaths)
+  // Lo conservado entra con el digest del molde, no con el del disco: la diferencia entre los dos es
+  // justamente lo que `localChanges` tiene que ver para que `upgrade` se detenga antes de pisar el
+  // archivo de la empresa. Sólo se pisan claves que ya están: el manifiesto declara lo que Cauce
+  // rastrea, y un archivo propio fuera de esa frontera no le incumbe.
+  for (const [file, hash] of Object.entries(preserved)) {
+    const relative = path.relative(root, file).split(path.sep).join('/')
+    if (relative in deliveredPaths) deliveredPaths[relative] = hash
+  }
   M.write(root, deliveredPaths)
   // La instancia recuerda de qué versión salió: sin esto no hay actualización posible.
   const configFile = path.join(root, 'ops.config.json')
@@ -305,12 +288,23 @@ function upgrade(dir, cli) {
   const overrides = O.overrides(root)
 
   if (dry) {
+    // Lo editado localmente se informa siempre, antes de mirar versiones: son dos preguntas distintas
+    // —«¿hay algo más nuevo?» y «¿qué tengo editado que se perdería?»— y la segunda tiene respuesta
+    // útil aunque la primera sea que no. Sin esto, el único modo que no toca nada era también el único
+    // que no podía avisar del conflicto, justo en el estado normal entre actualizaciones: `init` fija
+    // la versión exacta, así que instancia y motor coinciden casi todo el tiempo.
+    for (const file of changed) console.log(`  editado localmente: ${file}`)
     if (from === to) {
       // Contra el motor instalado, no contra lo publicado: la comparación es local y sin red. Decirlo
       // importa porque `init` fija la versión exacta, así que el motor no se mueve solo y esta línea,
       // a secas, se leía como «no hay nada nuevo» durante todas las versiones siguientes.
       console.log(`= ${to}: la instancia está al día con el motor instalado`)
-      return console.log('  para traer una versión más nueva: npm install --save-dev @ingeniomaps/cauce@latest')
+      // Con `--save-exact` porque npm guarda con caret por defecto, y el caret es lo que volvería
+      // falsa la línea de arriba: dentro de 0.x alcanza a los patches, y Cauce publica patches.
+      console.log('  para traer una versión más nueva:'
+        + ' npm install --save-exact --save-dev @ingeniomaps/cauce@latest')
+      if (changed.length) process.exit(1)
+      return
     }
     // Hacia atrás también es legítimo —una versión rompió algo y se vuelve—, pero anunciarlo como «hay
     // una versión más nueva» era mentir con el número a la vista. Y lo que corresponde imprimir es lo
@@ -322,7 +316,6 @@ function upgrade(dir, cli) {
       console.log(`⚠ hay una versión más nueva: ${to} (la instancia tiene ${from || 'una previa'})`)
       printChangelog(from, to)
     }
-    for (const file of changed) console.log(`  editado localmente: ${file}`)
     process.exit(1)
   }
 
@@ -416,18 +409,27 @@ function upgrade(dir, cli) {
   const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   config.cauceVersion = to
   F.atomicWriteJson(path.join(root, 'ops.config.json'), config)
+  // Acá es donde las tres versiones se saben a la vez, así que es donde pueden quedar diciendo lo mismo.
+  const pinned = pinEngine(root, to)
 
   console.log(`✓ Cauce ${from || '(previa)'} → ${to}`)
   // Descartar con --force es legítimo; hacerlo sin dejar rastro no. Queda en la salida del comando,
   // que es la evidencia que el protocolo pide para cualquier cambio.
   for (const file of changed) console.log(`− descartado tu cambio en ${file}`)
   for (const relative of retired) console.log(`− retirado ${relative}: Cauce ya no lo distribuye`)
+  // Se dice porque cambia un archivo que la empresa versiona, y porque explica un diff que si no
+  // aparecería sin autor. Ilegible se avisa y no se toca: el manifiesto es del repo anfitrión.
+  if (pinned === 'ilegible') console.log('  ⚠ package.json no se pudo leer: su versión quedó como estaba')
+  else if (pinned) console.log(`  package.json: ${pinned} → ${to}, la versión exacta que acabás de aplicar`)
   printChangelog(from, to)
   console.log(`  ${system.length} ruta(s) del sistema y ${O.RUNTIME_PATHS.length} del runtime actualizadas`)
   for (const override of overrides) {
     console.log(`= conservado ${override.collection}/${override.project}: sobrescribe ${override.system}`)
   }
-  console.log('  planning, organization y todo lo propio quedaron intactos')
+  // Sólo cuando es cierto. Llegar acá con algo en `changed` significa que se corrió con --force y se
+  // descartó contenido de la empresa: las líneas de arriba lo enumeran, y afirmar a continuación que
+  // todo lo propio quedó intacto contradice a la única señal que recibe quien corrió el comando.
+  if (!changed.length) console.log('  planning, organization y todo lo propio quedaron intactos')
   // No se borra: sin la dependencia declarada, quitarle `.ops/` la dejaría sin motor. Se avisa y
   // decide una persona.
   if (fs.existsSync(path.join(root, '.ops', 'engine'))) {

package/engine/cli/ops.js

@@ -21,8 +21,14 @@ const DEFAULT_TARGET = 'ops'
 // de otra— y el proyecto quedaba llamándose «acme-ops». La carpeta que ya nombra al toolkit es la
 // instancia; no hay una segunda adentro.
 function implicitTarget(cwd) {
-  const base = path.basename(cwd)
-  return base === DEFAULT_TARGET || base.endsWith('-ops') ? '.' : DEFAULT_TARGET
+  return isInstanceDir(cwd) ? '.' : DEFAULT_TARGET
+}
+
+// La misma heurística, aplicada al destino ya resuelto: una carpeta que ya nombra al toolkit **es** la
+// instancia, y el código de la empresa vive al lado.
+function isInstanceDir(dir) {
+  const base = path.basename(dir)
+  return base === DEFAULT_TARGET || base.endsWith('-ops')
 }
 
 // El nombre sale de la carpeta del proyecto, no de la que aloja la instancia: `ops/` y `acme-ops/`
@@ -73,7 +79,12 @@ async function init(target, cli) {
   // install` ya asume —el wiring del runner va al padre, donde se abre la herramienta—, así que lo
   // único que faltaba era que fuera lo que pasa cuando no se elige nada.
   const root = path.resolve(target || implicitTarget(process.cwd()))
-  const mode = cli.value('--mode', target ? 'embedded' : 'sidecar')
+  // El modo lo decide a dónde apunta el destino, no si alguien escribió el argumento. `init` e `init .`
+  // resuelven el mismo directorio y elegían modos opuestos: escribir el punto —la forma más natural de
+  // decir «acá»— daba embedded, y ahí la raíz del workspace pasa a ser la carpeta ops misma, así que
+  // `guard-workspace-boundary` deja de reconocer los repos hermanos y el wiring del runner se escribe
+  // adentro en vez de al lado, donde el dev abre su herramienta.
+  const mode = cli.value('--mode', isInstanceDir(root) ? 'sidecar' : 'embedded')
   if (!['embedded', 'sidecar'].includes(mode)) fail('--mode debe ser embedded o sidecar.', 2)
   const name = cli.value('--name', defaultName(root))
   const force = cli.has('--force')

package/package.json

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

package/template/Makefile

@@ -29,7 +29,7 @@ destroy: ## Muestra qué se pierde al borrar esta instancia (borrar exige --forc
 	@node tools/ops.js destroy .
 
 upgrade: ## Trae la última versión de Cauce y la aplica, sin tocar lo del proyecto
-	@npm install --save-dev @ingeniomaps/cauce@latest
+	@npm install --save-exact --save-dev @ingeniomaps/cauce@latest
 	@node tools/ops.js upgrade .
 
 automation-check: ## Comprueba hooks, workflows y adaptadores