@ingeniomaps/cauce 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -14,6 +14,52 @@ 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.57.0] - 2026-09-03
+
+### Agregado
+
+- **`organization/workspace.md`: dónde va lo que sólo sabe tu proyecto.** El mapa real, las
+  integraciones con su entorno concreto y las excepciones de autonomía. Es tuyo y `upgrade` no lo toca.
+  Hasta ahora el paso 2 del README te mandaba completar `AGENTS.md`, que es del toolkit y se reemplaza
+  entero: no perdías nada —desde 0.55.0 el `upgrade` se detiene y lo nombra— pero te tocaba fusionar a
+  mano en cada versión, sobre el único archivo garantizado a entrar en conflicto. Es la separación que
+  el toolkit ya usa en `planning/rules/system/` y en `planning/delivery/project.md`.
+
+  **Si ya llenaste tu `AGENTS.md`**: movés esas secciones a `organization/workspace.md` y listo. El
+  `upgrade` te lo dice cuando se detenga, antes de que puedas descartarlas con `--force`.
+
+### Corregido
+
+- **`check` te dice qué reglas deja de regir un override.** Un archivo propio con el nombre de uno de
+  `system/` lo reemplaza entero, no las reglas que mencionás: las que ese archivo definía y el tuyo no
+  redefine dejan de existir para tu proyecto. La advertencia nombraba el par de archivos y se leía como
+  benigna. El caso caro es una regla que el motor **sigue exigiendo** —R17 lo hace—: quedaba exigida sin
+  estar escrita en ningún lado. Ahora dice cuáles: `deja de regir R2, R17…`. Sigue siendo advertencia.
+
+- **Instalar un runner ya no hace que `upgrade` te acuse de editar `AGENTS.md`.** En modo `embedded`,
+  `automation install` con Codex escribe sus instrucciones dentro de ese archivo, entre marcas. El
+  registro anotaba el bloque en un solo lado, así que el `upgrade` siguiente se detenía sobre un archivo
+  que nadie había tocado —lo había escrito el comando que el README manda correr justo después—. Lo que
+  vos escribas alrededor se sigue detectando igual.
+
+## [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

package/README.md

@@ -224,7 +224,9 @@ equivalentes.
 Después de inicializar:
 
 1. Edita `ops.config.json`: nombre, modo y raíces de código.
-2. Completa `AGENTS.md`: límites de autonomía e integraciones reales.
+2. Completa `organization/workspace.md`: el mapa real, las integraciones con su entorno y las
+   excepciones de autonomía. Es del proyecto y `upgrade` no lo toca; `AGENTS.md`, en cambio, lo
+   mantiene Cauce entero.
 3. Completa `organization/company.md` y `organization/product.md` con el contexto estable de la empresa.
 4. Copia `planning/roadmap/epic-000-template.md` a `epic-001-<slug>.md`.
 5. Ejecuta `node tools/ops.js check planning` antes de activar cualquier runner.
@@ -266,13 +268,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

@@ -32,21 +32,17 @@ function mergeConfig(current, incoming) {
   return incoming
 }
 
-// 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|$)/
 
-// 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.
+// Si una entrada de hook la puso Cauce. Lo nuestro es lo que efectivamente entregamos, no todo lo que
+// vive en nuestra carpeta: `template/AGENTS.md` invita al proyecto a poner su guard justo ahí y le
+// promete que sobrevive a cada actualización, así que reconocer por directorio lo desregistraba en
+// cada reinstalación —el archivo quedaba en disco y el guard dejaba de correr—.
+//
+// Por eso son dos fuentes y no una. `expectedHooks()` es lo que entrega el motor de hoy, y alcanza
+// para una instancia que nunca instaló; `delivered` es lo que ésta registró haber recibido, y es lo
+// único que reconoce un guard que entregamos en una versión y retiramos en la siguiente, cuyo nombre
+// ya no está en la primera. Un guard del proyecto no está en ninguna de las dos, y sobrevive.
 function isDelivered(command, delivered) {
   const hit = String(command).match(HOOK_PATH)
   if (!hit) return false
@@ -58,6 +54,8 @@ function deliveredHookCommands(commands) {
   return [...commands].filter((command) => HOOK_PATH.test(String(command)))
 }
 
+// Saca del archivo del usuario lo que pusimos nosotros, para que el merge deje exactamente las
+// entradas de esta versión y ni una más.
 function withoutDeliveredHooks(config, live, delivered = new Set()) {
   const dropped = []
   const walk = (node) => {
@@ -105,12 +103,10 @@ function reportRemoved(name, dropped, live, output) {
 function includesConfig(actual, expected) {
   if (Array.isArray(expected)) {
     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.
+      // Un grupo de hooks se compara por su contenido y no por su forma serializada, porque la
+      // instalación promete conservar lo que el proyecto ya tenía: con el ítem entero como unidad, un
+      // grupo con un hook propio de más contaba como ausente y `doctor` llamaba divergente a una
+      // configuración completa.
       if (item && typeof item === 'object' && Array.isArray(item.hooks)) {
         return value && typeof value === 'object'
           && value.matcher === item.matcher

package/engine/automation/index.js

@@ -384,8 +384,6 @@ 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))
-  // 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: [] }
@@ -399,9 +397,8 @@ 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.
+  // Se anota lo que instalamos, 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)]
@@ -417,6 +414,13 @@ function install(root, name, output = console, options = {}) {
         output.log(`✓ ${name}: sus instrucciones quedaron dentro de ${resolved.item.target}`)
       }
       deliveredPaths[deliveryKey(name, resolved.item.target)] = M.digest(resolved.target)
+      // Y en la otra sección, porque este archivo está en las dos: `AGENTS.md` es del sistema y es
+      // donde este runner deja su bloque. Anotarlo sólo acá dejaba a `localChanges` comparando contra
+      // el digest previo al bloque, así que el `upgrade` siguiente se detenía echándole a la empresa
+      // una edición que había hecho el comando de al lado. Lo que la empresa escriba alrededor cambia
+      // el digest igual, así que se sigue viendo.
+      const own = path.relative(root, resolved.target).split(path.sep).join('/')
+      if (O.SYSTEM_FILES.includes(own)) M.write(root, M.recordPaths(root, [own], M.read(root)))
       continue
     }
     if (status === 'ajeno' && ownFile) {

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,10 +30,8 @@ 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.
+// Devuelve, por archivo conservado, el digest de lo que **habría** escrito. Quien registra la entrega
+// necesita esos dos contenidos distintos, y el que quedó en disco no es uno de ellos.
 function copyTemplate(source, target, replacements, force, skip = [], quiet = false) {
   F.assertNoSymlinkPath(path.dirname(target), target)
   fs.mkdirSync(target, { recursive: true })
@@ -86,47 +85,6 @@ function copyRuntime(source, target, preserve = false, boundary = target, skip =
   return preserved
 }
 
-// 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']
-}
-
 // 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.
@@ -155,10 +113,13 @@ 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.
+  // Adoptar Cauce en un repositorio con contenido es `init --force`, y lo que se conserva ahí lo
+  // escribió la empresa. Registrarlo hasheando el disco lo declaraba entregado por Cauce con contenido
+  // que Cauce nunca entregó, así que `localChanges` no veía ninguna edición y el `upgrade` siguiente lo
+  // reemplazaba: entra con el digest del molde, y esa diferencia es lo que detiene al upgrade.
+  //
+  // 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
@@ -301,6 +262,51 @@ function renameTeamsToFlows(root) {
   return moved
 }
 
+// Qué hacer en vez de haber editado, según a quién pertenece cada archivo que se perdería. Vive
+// aparte de `upgrade` porque su reloj es el de la frontera de propiedad y el de la redacción del
+// consejo, no el del procedimiento que lo imprime, y porque así se puede probar sin tocar el disco.
+//
+// Tres clases distintas, y antes eran dos: todo lo que no vivía bajo `system/` recibía el consejo del
+// runtime, así que editar el protocolo respondía con cómo desactivar un guard. Decirle a alguien la
+// salida ajena lo manda a buscar una configuración que no existe.
+function adviceFor(changed) {
+  const ruleFiles = changed.filter((file) => file.includes('/system/'))
+  const runtime = changed.filter((file) => !file.includes('/system/')
+    && O.RUNTIME_PATHS.some((base) => file.startsWith(`${base}/`)))
+  const docs = changed.filter((file) => !ruleFiles.includes(file) && !runtime.includes(file))
+  const advice = []
+  if (ruleFiles.length) {
+    advice.push(
+      'Las ruleFiles y decisiones bajo system/ son del toolkit. Para cambiar una, escribí la tuya al\n'
+      + 'lado con el mismo ID: el proyecto manda y `check` lo reporta como override explícito.',
+    )
+  }
+  if (runtime.length) {
+    advice.push(
+      'El runtime es del toolkit: en vez de editarlo, agregá lo tuyo al lado con otro nombre —un\n'
+      + 'guard propio sobrevive a cada actualización— y registralo en la configuración de tu runner,\n'
+      + 'que sí es del proyecto. Para desactivar un guard alcanza con quitarlo de esa configuración.',
+    )
+  }
+  if (docs.length) {
+    advice.push(
+      'Esos docs son del toolkit y no llevan una línea de la empresa: se reemplazan enteros en\n'
+      + 'cada actualización para que las mejoras lleguen. Lo que tu proyecto decide distinto va donde sí\n'
+      + 'es suyo —una ADR propia, una regla propia, o `planning/delivery/project.md` para la entrega—.',
+    )
+  }
+  // `AGENTS.md` se lo gana aparte porque hasta ahora el README mandaba completarlo, así que el consejo
+  // genérico de arriba —«no llevan una línea de la empresa»— le miente justo a quien le hizo caso.
+  if (docs.includes('AGENTS.md')) {
+    advice.push(
+      'En `AGENTS.md` en particular: el mapa real, las integraciones y las excepciones de autonomía\n'
+      + 'ahora van en `organization/workspace.md`, que es del proyecto y no se reemplaza. Movelos ahí\n'
+      + 'antes de repetir con --force, o los vas a tener que fusionar de nuevo en cada versión.',
+    )
+  }
+  return advice.join('\n\n')
+}
+
 // Actualiza sólo lo que el toolkit declara suyo. Todo lo demás —planning, organization, reglas
 // propias, agentes editados— queda intacto por construcción, no por comparación.
 function upgrade(dir, cli) {
@@ -328,18 +334,19 @@ 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.
+    // Antes de mirar versiones, porque 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.
+    // Adentro del `if` de abajo, el único modo que no toca nada era el único que no podía avisar.
     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`)
-      console.log('  para traer una versión más nueva: npm install --save-dev @ingeniomaps/cauce@latest')
+      // Con `--save-exact`, sin el cual el caret de npm vuelve falsa la línea de arriba. Por qué, y por
+      // qué no alcanza con documentarlo, en `pinEngine`.
+      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
     }
@@ -368,37 +375,9 @@ function upgrade(dir, cli) {
 
   if (changed.length && !force) {
     for (const file of changed) console.error(`✗ ${file}`)
-    // Tres clases distintas, y antes eran dos: todo lo que no vivía bajo `system/` recibía el consejo
-    // del runtime, así que editar el protocolo respondía con cómo desactivar un guard. Cada una tiene
-    // su salida y decirle la ajena manda a buscar una configuración que no existe.
-    const ruleFiles = changed.filter((file) => file.includes('/system/'))
-    const runtime = changed.filter((file) => !file.includes('/system/')
-      && O.RUNTIME_PATHS.some((base) => file.startsWith(`${base}/`)))
-    const docs = changed.filter((file) => !ruleFiles.includes(file) && !runtime.includes(file))
-    const advice = []
-    if (ruleFiles.length) {
-      advice.push(
-        'Las ruleFiles y decisiones bajo system/ son del toolkit. Para cambiar una, escribí la tuya al\n'
-        + 'lado con el mismo ID: el proyecto manda y `check` lo reporta como override explícito.',
-      )
-    }
-    if (runtime.length) {
-      advice.push(
-        'El runtime es del toolkit: en vez de editarlo, agregá lo tuyo al lado con otro nombre —un\n'
-        + 'guard propio sobrevive a cada actualización— y registralo en la configuración de tu runner,\n'
-        + 'que sí es del proyecto. Para desactivar un guard alcanza con quitarlo de esa configuración.',
-      )
-    }
-    if (docs.length) {
-      advice.push(
-        'Esos docs son del toolkit y no llevan una línea de la empresa: se reemplazan enteros en\n'
-        + 'cada actualización para que las mejoras lleguen. Lo que tu proyecto decide distinto va donde sí\n'
-        + 'es suyo —una ADR propia, una regla propia, o `planning/delivery/project.md` para la entrega—.',
-      )
-    }
     fail(
       `\n${changed.length} archivo(s) que mantiene Cauce fueron editados y se perderían.\n\n` +
-      `${advice.join('\n\n')}\n\nSi el cambio ya no te sirve, repetí con --force para descartarlo.`,
+      `${adviceFor(changed)}\n\nSi el cambio ya no te sirve, repetí con --force para descartarlo.`,
     )
   }
 
@@ -446,20 +425,25 @@ 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 explica un diff en un archivo que la empresa versiona, y que si no aparecería sin
+  // autor.
+  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}`)
   }
-  // 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.
+  // Sólo cuando es cierto: llegar acá con algo en `changed` es haber descartado contenido de la
+  // empresa con --force, que las líneas de arriba enumeran.
   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.
@@ -481,4 +465,4 @@ function upgrade(dir, cli) {
   for (const entry of FK.drift(root)) console.log(`  ⚠ ${FK.driftLine(entry)}`)
 }
 
-module.exports = { copyTemplate, scaffold, providerNames, upgrade, destroy, PROJECT_ROOT }
+module.exports = { copyTemplate, scaffold, providerNames, adviceFor, upgrade, destroy, PROJECT_ROOT }

package/engine/cli/ops.js

@@ -16,21 +16,20 @@ const BOOT = require('./bootstrap')
 // Dónde aterriza una instancia cuando nadie eligió: una carpeta propia junto al código.
 const DEFAULT_TARGET = 'ops'
 
-// Dónde va la instancia cuando nadie eligió destino. Parada frecuente: el dev ya creó `acme-ops/` y
-// corre `init` adentro. Sin esto la instancia caía en `acme-ops/ops/` —una carpeta del toolkit dentro
-// 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) {
-  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.
+// Una carpeta que ya nombra al toolkit **es** la instancia; no hay una segunda adentro, y el código de
+// la empresa vive al lado. Es la única regla, y de ella salen las dos decisiones que `init` toma sin
+// que nadie las escriba: dónde aterriza y en qué modo.
 function isInstanceDir(dir) {
   const base = path.basename(dir)
   return base === DEFAULT_TARGET || base.endsWith('-ops')
 }
 
+// Parada frecuente: el dev ya creó `acme-ops/` y corre `init` adentro. Sin esto la instancia caía en
+// `acme-ops/ops/` y el proyecto quedaba llamándose «acme-ops».
+function implicitTarget(cwd) {
+  return isInstanceDir(cwd) ? '.' : DEFAULT_TARGET
+}
+
 // El nombre sale de la carpeta del proyecto, no de la que aloja la instancia: `ops/` y `acme-ops/`
 // nombran al toolkit, y quien lee `project` en la configuración espera leer «acme».
 function defaultName(root) {
@@ -79,11 +78,9 @@ 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()))
-  // 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.
+  // Del destino resuelto y no de si alguien escribió el argumento: `init` e `init .` apuntan al mismo
+  // directorio y elegían modos opuestos, así que escribir el punto daba el layout contrario al de
+  // arriba sin que nadie lo pidiera.
   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))

package/engine/cli/planning.js

@@ -80,7 +80,13 @@ function check(dir, cli) {
   // Sobrescribir una entrada de system/ es legítimo y esperado; lo que no puede pasar es que
   // ocurra en silencio, porque esa entrada deja de recibir las mejoras del toolkit.
   for (const override of O.overrides(path.resolve(root, '..'))) {
-    warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} (override explícito)`)
+    // Y con qué se queda el proyecto: un override sano redefine lo que reemplaza, y el que deja IDs
+    // afuera los retira sin decirlo. Nombrarlos es lo único que separa una decisión de un descuido.
+    const retired = override.collection === 'planning/rules'
+      ? PC.retiredByOverride(root, override.project)
+      : []
+    warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} `
+      + `(override explícito)${retired.length ? `; deja de regir ${retired.join(', ')}` : ''}`)
   }
   // Misma regla para los cargos, que es donde más caro sale: un fork se hace una vez y se olvida.
   const FK = require('../agents/fork')

package/engine/cli/wiring.js

@@ -179,7 +179,8 @@ function onboard(rootArg, cli, runner = '') {
   console.log(runner
     ? `\n→ Abrí ${runner} acá y contestale esa pregunta.`
     : '\n→ Contestá esa pregunta cuando corras el arranque.')
-  console.log('  Con tus respuestas escribe organization/, el mapa real de AGENTS.md y la primera épica.')
+  console.log('  Con tus respuestas escribe organization/, el mapa real en'
+    + ' organization/workspace.md y la primera épica.')
 }
 
 // El registro de proveedores, leído igual por todos los que lo tocan. `list` lo parseaba suelto y un

package/engine/core/onboarding.js

@@ -74,7 +74,7 @@ function guide(root, services = []) {
 function missingSections(root) {
   const warnings = []
   const template = path.join(PACKAGE_ROOT, 'template', 'organization')
-  for (const name of ['company.md', 'product.md', 'domains.md']) {
+  for (const name of ['company.md', 'product.md', 'domains.md', 'workspace.md']) {
     const written = path.join(root, 'organization', name)
     if (!fs.existsSync(written) || !fs.existsSync(path.join(template, name))) continue
     const headings = (text) => new Set((text.match(/^##\s+(.+)$/gm) || []).map((line) => line.trim()))
@@ -99,7 +99,11 @@ function missingSections(root) {
 // Sólo cuando la instancia ya tiene contexto escrito: antes del arranque no hay dónde estuvieran.
 function orphanCredentials(root) {
   if (guide(root).fresh) return []
-  const contracts = ['AGENTS.md', path.join('planning', 'HUMAN_ACTIONS.md')]
+  // El mapa del proyecto vive en `organization/workspace.md` desde que `AGENTS.md` pasó a ser del
+  // toolkit entero; el viejo se sigue mirando porque una instancia anterior lo tiene ahí y una
+  // credencial ya declarada no debería volver a reportarse como huérfana por haber mudado el archivo.
+  const contracts = [path.join('organization', 'workspace.md'), 'AGENTS.md',
+    path.join('planning', 'HUMAN_ACTIONS.md')]
     .map((file) => { try { return fs.readFileSync(path.join(root, file), 'utf8') } catch { return '' } })
     .join('\n')
   if (!contracts) return []

package/engine/planning/contracts.js

@@ -172,6 +172,19 @@ function ruleIds(file) {
   return [...P.read(file).matchAll(/^##\s+([A-Z]\d+)\s+[—-]/gm)].map((match) => match[1])
 }
 
+// Qué IDs deja de regir un override por nombre: los que definía el archivo del sistema y el propio no
+// redefine. Reemplazar el archivo entero es la función del override y está documentada; lo que no se
+// veía es la consecuencia, porque la advertencia nombraba el par de archivos y no la diferencia. El
+// caso caro es una regla que el motor sigue exigiendo —R17 lo hace—: queda exigida y sin estar escrita
+// en ningún lado, y quien la vea fallar la va a buscar en `rules/`, donde ya no está.
+function retiredByOverride(dir, name) {
+  const rules = path.join(dir, 'rules')
+  const system = path.join(rules, 'system', name)
+  if (!fs.existsSync(system)) return []
+  const redefined = ruleIds(path.join(rules, name))
+  return ruleIds(system).filter((id) => !redefined.includes(id))
+}
+
 function validateRules(dir) {
   const rules = path.join(dir, 'rules')
   const owner = new Map()
@@ -418,6 +431,7 @@ module.exports = {
   oversizedUnits,
   validateAdr,
   validateRules,
+  retiredByOverride,
   validateBacklogStructure,
   validCommitTrace,
   validDecisionTrace,

package/package.json

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

package/template/AGENTS.md

@@ -2,24 +2,18 @@
 
 Este archivo gobierna el qué y el cuándo. `planning/PROTOCOL.md` gobierna el flujo y
 `planning/rules/` el cómo: sus reglas rigen cada tarea y se leen antes de empezar, no cuando algo sale
-mal. Ahí está la conducta que no depende de este proyecto —trato con sistemas externos, qué se debe
-entregar aun al negarse—; acá, lo que sí depende.
+mal. Los tres los mantiene Cauce y valen para cualquier proyecto. Lo que este proyecto tiene de propio
+—su mapa, sus integraciones, hasta dónde llega la autonomía acá— vive en `organization/workspace.md`.
 
-## Mapa real
+## Qué sabe este proyecto y no este archivo
 
-Completar antes de la primera tarea:
+El mapa real —qué se construye, qué repos existen, qué está fuera de alcance—, las integraciones con su
+entorno concreto y las excepciones de autonomía viven en **`organization/workspace.md`**, que es del
+proyecto y `upgrade` no toca. Acá no: este archivo lo mantiene Cauce y se reemplaza entero en cada
+actualización, así que lo que escribieras se perdería o te haría fusionar a mano todas las veces.
 
-- Qué producto se construye.
-- Qué repos o servicios existen y dónde viven.
-- Dónde documenta cada servicio sus comandos de test, lint y build.
-- Qué directorios son legacy o están fuera de alcance.
-
-El mapa no debe duplicar documentación técnica: enlaza a la fuente de verdad de cada servicio.
-
-## Integraciones y ambientes
-
-R12 fija el trato con todo sistema externo: real y de sólo lectura mientras no se lo nombre como
-sandbox. Las excepciones de este proyecto —y sólo ellas— van acá, con el entorno concreto.
+Es la misma separación que `planning/rules/system/` con las reglas propias y que `planning/delivery/`
+con `project.md`: lo que el toolkit mejora, aparte de lo que sólo vos podés escribir.
 
 ## Cargos disponibles
 
@@ -130,6 +124,9 @@ Registra la acción exacta en `planning/HUMAN_ACTIONS.md` y, si bloquea todo, cr
 Nunca amplía el alcance, promueve sus propias ideas, reescribe el proceso durante una tarea, usa
 `git add .`/`git add -A`, hace push/force/amend, ni afirma éxito sin evidencia real.
 
+Eso rige sin que nadie escriba nada. Lo que este proyecto amplíe o restrinja va en
+`organization/workspace.md`, con su razón; los cuatro límites del párrafo anterior no se amplían ahí.
+
 ## Definición de terminado
 
 1. La aceptación se observa y queda cubierta por pruebas cuando existe superficie testeable.

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

package/template/organization/README.md

@@ -7,6 +7,8 @@ Con molde, y `check` avisa si a alguno le faltan secciones del original:
 - `company.md`: misión, modelo de negocio, objetivos, estructura y derechos de decisión.
 - `product.md`: problema, usuarios, propuesta de valor y límites.
 - `domains.md`: lenguaje ubicuo, dominios y dueños.
+- `workspace.md`: el mapa real, las integraciones con su entorno y las excepciones de autonomía.
+  Es lo que `AGENTS.md` no puede llevar: ese archivo lo mantiene Cauce y se reemplaza al actualizar.
 
 Recomendados, sin molde: escribilos con la forma que le sirva a este proyecto.
 

package/template/organization/workspace.md

@@ -0,0 +1,34 @@
+# Este workspace
+
+Lo que sólo sabe este proyecto: qué hay, contra qué se conecta y hasta dónde puede decidir solo un
+runner. `AGENTS.md` gobierna el qué y el cuándo para cualquier proyecto; esto es lo que cambia entre
+uno y otro, y por eso vive acá, donde Cauce no escribe: `upgrade` no lo toca nunca.
+
+## Mapa real
+
+Completar antes de la primera tarea:
+
+- Qué producto se construye.
+- Qué repos o servicios existen y dónde viven.
+- Dónde documenta cada servicio sus comandos de test, lint y build.
+- Qué directorios son legacy o están fuera de alcance.
+
+El mapa no debe duplicar documentación técnica: enlaza a la fuente de verdad de cada servicio.
+
+## Integraciones y ambientes
+
+R12 fija el trato con todo sistema externo: real y de producción mientras no se lo nombre como sandbox.
+Las excepciones de este proyecto —y sólo ellas— van acá, nombrando el entorno concreto.
+
+Las credenciales que cada integración necesita se nombran acá o en `planning/HUMAN_ACTIONS.md`, con
+quién las carga y dónde: `check` avisa cuando el proyecto declara una variable que no aparece en
+ninguno de los dos, porque una credencial sin dueño no rompe nada hasta el día del despliegue.
+
+## Excepciones de autonomía
+
+Los límites que rigen sin escribir nada están en `AGENTS.md`, y son los mismos para todo proyecto. Acá
+va lo que este proyecto amplía o restringe, con su razón: un servicio donde el runner no puede tocar
+migraciones, un repo donde sí puede commitear directo, un entorno de pruebas que es seguro escribir.
+
+Lo que no se puede ampliar acá: promover trabajo propio, prometer fechas, inventar evidencia o exceder
+la autoridad de un cargo. Eso no depende del proyecto.

package/template/planning/rules/README.md

@@ -19,4 +19,10 @@ fuera de él para que no existan dos reglas con el mismo nombre.
 Para cambiar una regla del sistema, escribí la tuya **con el mismo nombre de archivo**: ahí redefinir
 sus números es la función, la del proyecto manda, y `check` reporta el override en vez de fallar.
 
+Lo que reemplaza es **el archivo entero, no las reglas que mencionás**: las que ese archivo del sistema
+definía y el tuyo no redefine dejan de regir para tu proyecto. Alguna la sigue exigiendo el motor —R17
+lo hace—, y ahí queda exigida sin estar escrita en ningún lado. Por eso `check` te dice cuáles son
+—«deja de regir R2, R17…»— y por eso conviene, antes de sobrescribir un archivo, mirar si lo tuyo era
+una regla nueva: si lo era, va acá al lado como `P1..Pn` y no se lleva nada puesto.
+
 Las convenciones específicas de lenguaje viven junto al servicio que usa ese lenguaje.