@ingeniomaps/cauce 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -14,6 +14,43 @@ 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.60.0] - 2026-09-03
+
+### Corregido
+
+- **La épica que promueve una integración pasa `check`.** La descripción remota trae sus propios
+  encabezados —el fixture de Jira trae `## Criterios de aceptación`— y quedaban compitiendo con los que
+  escribe la promoción, así que el parser leía la sección importada, que no tiene ningún criterio, y el
+  planning quedaba en rojo apenas promovías. Ahora lo importado baja un nivel al entrar, el parser
+  prefiere la coincidencia exacta cuando existe —`## Historias (Tareas)` sigue resolviendo— y el
+  criterio sale sin el guión de la viñeta pegado.
+
+- **Curar un draft ya no deja la integración en rojo.** El README manda editar el draft y correr
+  `check`, y ese `check` fallaba: editar deja obsoleto un flag de `remote.json` que sólo se recalcula en
+  `sync`, `rebase` y `reconcile`. Dejó de exigirse porque no protegía nada: se leía en un único lugar,
+  la validación que lo comparaba consigo mismo, y lo que decide qué vuelve al remoto compara el
+  contenido. **Qué cambia para vos**: el recorrido documentado funciona sin pasos intermedios.
+
+- **`/onboard` escribe el mapa donde vive desde 0.57.0.** Seguía mandándolo a `AGENTS.md`, así que el
+  primer recorrido de una instancia nueva deshacía el arreglo que sacó de ahí lo que sólo sabe tu
+  proyecto. Ahora escribe las tres secciones de `organization/workspace.md` —incluidas integraciones y
+  excepciones de autonomía, que ningún recorrido llenaba— y suma `organization/domains.md`, que no
+  nombraba.
+
+- **`upgrade` te dice cuando se lleva las instrucciones de tu runner.** `AGENTS.md` es del toolkit y se
+  reemplaza entero, con el bloque que `automation install` dejó adentro. Lo recuperás reinstalando —el
+  propio `upgrade` te lo recuerda— pero ese recordatorio no tenía causa visible, y el bloque desaparecía
+  sin explicación. Ahora se nombra el archivo y el runner, una sola vez.
+
+- **`check` avisa cuando dos secciones de una épica compiten por el mismo rol.** El parser prefiere la
+  exacta, así que resuelve — en silencio, y quien escribió las dos no se entera de que una se ignora
+  entera. Un título con sufijo como `## Historias (Tareas)` no dispara nada: es el único de su rol.
+
+- **`/autobuild` ve las excepciones de autonomía de tu proyecto.** Armaba sus límites leyendo sólo
+  `AGENTS.md`, y desde 0.57.0 los tuyos están en `organization/workspace.md`. Lo que viajaba a cada
+  subagente como «Límites del proyecto» eran los genéricos del toolkit. Ahora ese archivo entra en la
+  lectura única de Triage; si no existe o su sección sigue como la trae el molde, no se inventa ninguno.
+
 ## [0.59.0] - 2026-09-03
 
 ### Corregido

package/automatization/workflows/autobuild.js

@@ -29,6 +29,7 @@ export const meta = {
 {{INCLUDE:shared/workflow-root.js}}
 const CONFIG = `${ROOT}/ops.config.json`
 const P = `${ROOT}/planning`
+const ORG = `${ROOT}/organization`
 const BACKLOG = `${P}/BACKLOG.md`
 const DONE = `${P}/DONE.md`
 const WIP = `${P}/WIP.md`
@@ -263,15 +264,23 @@ phase = (name) => { ran.push(name); announce(name) }
 
 phase('Triage')
 // El contrato se lee una sola vez por corrida y viaja como texto: ningún subagente relee AGENTS.md,
-// ops.config.json ni PROTOCOL.md. `ops check` y el guard planning-drift siguen validando el resultado.
+// workspace.md, ops.config.json ni PROTOCOL.md. `ops check` y el guard planning-drift siguen validando
+// el resultado.
+//
+// `organization/workspace.md` está en esa lista desde que 0.57.0 sacó del `AGENTS.md` lo que sólo sabe
+// el proyecto: los límites que éste amplía o restringe viven ahí, y sin leerlo lo que viaja a cada
+// subagente como «Límites del proyecto» eran sólo los genéricos del toolkit.
 const contract = await agent(
-  `${BASE}\n\nLeé ${ROOT}/AGENTS.md, ${CONFIG} y ${P}/PROTOCOL.md una sola vez y no leas nada más. Reportá los ` +
+  `${BASE}\n\nLeé ${ROOT}/AGENTS.md, ${ORG}/workspace.md, ${CONFIG} y ${P}/PROTOCOL.md una sola vez y no ` +
+  `leas nada más. Reportá los ` +
   `valores de configuración textualmente: project, workspaceRoots como entradas "nombre → ruta", ` +
   `runner.maxTaskHours, runner.commitPerTask y runner.humanCheckpointBetweenMilestones como humanCheckpoint. ` +
   `En gates poné una entrada "ruta → comando" por cada workspaceRoot que declare \`verify\`, y ninguna por ` +
   `las que no lo declaren: la lista vacía significa que el proyecto no dice con qué se verifica. ` +
   `Copiá la sección "## Contratos" de PROTOCOL.md dentro de contracts tal cual, sin reformular, resumir ni ` +
-  `reordenar. En boundaries listá sólo los límites que AGENTS.md enuncia y que restringen la ejecución autónoma.`,
+  `reordenar. En boundaries listá los límites que AGENTS.md enuncia y las "Excepciones de autonomía" que ` +
+  `declare ${ORG}/workspace.md, que son las de este proyecto: si ese archivo no existe o su sección sigue ` +
+  `como la trae el molde, no inventes ninguna.`,
   { schema: CONTRACT, label: 'contract-digest' },
 )
 if (!contract) return stop('contract-unavailable', `no se pudo leer ${CONFIG} ni ${P}/PROTOCOL.md`)
@@ -281,7 +290,7 @@ const limits = bounds.length ? ` Límites del proyecto: ${bounds.join('; ')}.` :
 // Alcance de escritura: para subagentes que tocan código o ejecutan gates del producto.
 const SCOPE = `${BASE}\n\nProyecto ${contract.project}. workspaceRoots es el límite completo de escritura del ` +
   `producto: ${contract.workspaceRoots.join('; ')}.${limits} Este preámbulo ya trae el contrato; no vuelvas a leer ` +
-  `${ROOT}/AGENTS.md, ${CONFIG} ni ${P}/PROTOCOL.md.`
+  `${ROOT}/AGENTS.md, ${ORG}/workspace.md, ${CONFIG} ni ${P}/PROTOCOL.md.`
 // Formatos de planning: sólo para subagentes que escriben roadmap, BACKLOG, WIP, DONE o gates.
 const LEDGER = `${SCOPE}\n\nContratos de planning, textuales de ${P}/PROTOCOL.md:\n${contract.contracts}`
 

package/automatization/workflows/onboard.js

@@ -1,5 +1,5 @@
 // Arranque de una instancia recién creada: convierte un repositorio que nadie le explicó al toolkit en
-// contexto escrito —`organization/`, el mapa real de `AGENTS.md`, las raíces de código— y en la primera
+// contexto escrito —`organization/`, el mapa real en `organization/workspace.md`, las raíces— y en la primera
 // épica.
 //
 // El orden importa y se pagó caro: la primera versión le pedía a un agente que «inventariara el
@@ -153,7 +153,8 @@ phase('Draft')
 const drafted = await agent(
   `${BASE}\n\n${EVIDENCE}\n\nEscribí de una sola pasada el contexto de esta instancia, reemplazando el ` +
   `molde en vez de comentarlo:\n` +
-  `1. ${ORG}/company.md y ${ORG}/product.md: lo que la persona contó y los nombres del repositorio ` +
+  `1. ${ORG}/company.md, ${ORG}/product.md y ${ORG}/domains.md: lo que la persona contó y los nombres ` +
+  `del repositorio ` +
   `permiten afirmar. Lo que nada sostiene queda "Por definir" y su pregunta va a openQuestions. Una ` +
   `dimensión que no llegaste a preguntar no se completa deduciéndola: queda "Por definir" con su ` +
   `pregunta en openQuestions, aunque puedas imaginar la respuesta. Y lo que sí deducís de otra ` +
@@ -161,9 +162,14 @@ const drafted = await agent(
   `lo que alguien dijo. No des ` +
   `por sentado que el proyecto vende algo: puede sostenerse con donaciones, presupuesto interno o ` +
   `trabajo voluntario, y una sección que no aplica se dice, no se completa con algo plausible.\n` +
-  `2. La sección "## Mapa real" de ${ROOT}/AGENTS.md: una entrada por servicio con su ruta, su runtime y ` +
-  `sus comandos **tal como los declara**, diciendo de qué archivo salió cada uno. No afirmes que ` +
-  `funcionan: nadie los corrió. Un servicio sin comandos declarados se escribe así, que es información.\n` +
+  `2. ${ORG}/workspace.md, que es donde vive lo que sólo sabe este proyecto y \`upgrade\` no toca, con ` +
+  `sus tres secciones. En "## Mapa real", una entrada por servicio con su ruta, su runtime y sus ` +
+  `comandos **tal como los declara**, diciendo de qué archivo salió cada uno. No afirmes que ` +
+  `funcionan: nadie los corrió. Un servicio sin comandos declarados se escribe así, que es ` +
+  `información. En "## Integraciones y ambientes", las credenciales que cada una necesita, porque ` +
+  `\`check\` cruza ese archivo para avisar de las que nadie carga. Y "## Excepciones de autonomía" ` +
+  `sólo si el proyecto declaró alguna: lo que nada sostiene queda "Por definir" con su pregunta en ` +
+  `openQuestions.\n` +
   `3. ${ROOT}/ops.config.json: dejá en workspaceRoots las raíces de código reales, que es lo que un guard ` +
   `usa para bloquear una escritura fuera de lugar. Una raíz de más lo apaga.\n` +
   `${services.length ? '' : 'Sin servicios, el mapa queda declarado como pendiente, diciendo qué lo ' +

package/engine/automation/index.js

@@ -472,4 +472,5 @@ module.exports = {
   listHooks,
   runnerManifest,
   runnerPaths,
+  blockStart,
 }

package/engine/cli/instance.js

@@ -9,7 +9,6 @@ const fs = require('node:fs')
 const path = require('node:path')
 const F = require('../core/files')
 const O = require('../core/ownership')
-const CL = require('../core/changelog')
 const M = require('../core/manifest')
 const OB = require('../core/onboarding')
 const P = require('../planning/parser')
@@ -17,6 +16,7 @@ const ST = require('../planning/state')
 const A = require('../automation')
 const { fail } = require('./io')
 const { declareEngine, pinEngine, undeclareEngine } = require('./dependency')
+const { adviceFor, previewUpgrade, reportUpgrade } = require('./upgrade-report')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
@@ -134,17 +134,6 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
   return root
 }
 
-// Qué trae la versión nueva, leído del paquete: sin esto el reemplazo de system/ es a ciegas.
-function printChangelog(from, to) {
-  const notes = CL.between(CL.read(PROJECT_ROOT), from, to)
-  if (!notes.length) return
-  for (const note of notes) {
-    console.log(`\n  ── ${note.version} ──`)
-    for (const line of note.body.split('\n')) if (line.trim()) console.log(`  ${line}`)
-  }
-  console.log('')
-}
-
 function instanceVersion(root) {
   try {
     return JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8')).cauceVersion || ''
@@ -262,53 +251,6 @@ 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) {
   const root = path.resolve(dir || '.')
   if (!fs.existsSync(path.join(root, 'ops.config.json'))) {
@@ -333,34 +275,12 @@ function upgrade(dir, cli) {
   const changed = O.localChanges(root)
   const overrides = O.overrides(root)
 
+  // El código de salida lo aplica acá y no adentro: `--check` mira y cuenta, y quien decide qué hacer
+  // con lo que vio es el comando. Escondido en la función que informa, el corte del flujo no se ve.
   if (dry) {
-    // 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`)
-      // 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
-    }
-    // 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
-    // contrario: no lo que se gana, sino lo que se deja.
-    if (CL.compare(to, from) < 0) {
-      console.log(`↩ volvés a ${to} desde ${from}. Esto es lo que dejás de tener:`)
-      printChangelog(to, from)
-    } else {
-      console.log(`⚠ hay una versión más nueva: ${to} (la instancia tiene ${from || 'una previa'})`)
-      printChangelog(from, to)
-    }
-    process.exit(1)
+    const code = previewUpgrade({ from, to, changed })
+    if (code) process.exit(code)
+    return
   }
 
   // Antes de retirar nada, comprobar que no se lleve puesto aprendizaje acumulado.
@@ -385,7 +305,7 @@ function upgrade(dir, cli) {
   // incluye a propósito —lo reemplazaría en cada actualización, que es lo que un archivo del proyecto
   // no debe sufrir— así que sin este paso no llega por ninguna vía, y la instancia queda leyendo una
   // instrucción que apunta a un archivo que no tiene.
-  const settings = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
+  const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   const added = []
   for (const relative of O.addedPaths()) {
     const target = path.join(root, relative)
@@ -396,7 +316,7 @@ function upgrade(dir, cli) {
     fs.mkdirSync(path.dirname(target), { recursive: true })
     let content = fs.readFileSync(origin, 'utf8')
     for (const [key, value] of Object.entries({
-      '{{PROJECT_NAME}}': settings.project || path.basename(root),
+      '{{PROJECT_NAME}}': config.project || path.basename(root),
       '{{MODE}}': O.mode(root),
       '{{WORKSPACE_PATH}}': O.mode(root) === 'embedded' ? '.' : '..',
     })) content = content.replaceAll(key, value)
@@ -404,6 +324,21 @@ function upgrade(dir, cli) {
     added.push(relative)
   }
 
+  // Qué bloque de runner se lleva puesto el reemplazo. `AGENTS.md` es del toolkit y se reemplaza
+  // entero, con el bloque que `automation install` dejó adentro: la instancia lo recupera reinstalando
+  // —el recordatorio de abajo ya lo pide— pero sin decir esto ese recordatorio no tiene causa visible,
+  // y quien mire su archivo ve el bloque desaparecido sin explicación.
+  const droppedBlocks = []
+  for (const runner of [...new Set(Object.keys(M.readRunners(root)).map((key) => key.split('/')[0]))]) {
+    // Sólo los archivos sueltos: `system` trae también colecciones, y un bloque de runner vive en un
+    // archivo de instrucciones —hoy `AGENTS.md`—, nunca dentro de un directorio del sistema.
+    for (const relative of O.SYSTEM_FILES) {
+      const file = path.join(root, relative)
+      if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue
+      if (fs.readFileSync(file, 'utf8').includes(A.blockStart(runner))) droppedBlocks.push({ runner, relative })
+    }
+  }
+
   for (const relative of [...system, ...O.RUNTIME_PATHS]) {
     const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
     if (!fs.existsSync(origin)) continue
@@ -445,50 +380,12 @@ function upgrade(dir, cli) {
   ))
   M.write(root, M.prune(root, record), null, kept)
 
-  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`)
-  // Nombrarlos importa tanto como crearlos: existen para que los completes, y uno que aparece sin
-  // aviso no lo completa nadie.
-  for (const relative of added) console.log(`+ ${relative}: lo agrega esta versión, completalo`)
-  // 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` 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.
-  if (fs.existsSync(path.join(root, '.ops', 'engine'))) {
-    console.log('\n⚠ esta instancia tiene el motor vendorizado en .ops/, que Cauce ya no distribuye.')
-    console.log('  Corré "npm install" para tenerlo como dependencia y después borrá .ops/ a mano.')
-  }
-  // 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}`)
-  }
-  // Después de aplicar, no antes: recién acá el paquete tiene la versión nueva y la comparación dice
-  // algo. Es además el momento en que alguien está mirando qué le trajo la actualización.
-  const FK = require('../agents/fork')
-  for (const entry of FK.drift(root)) console.log(`  ⚠ ${FK.driftLine(entry)}`)
+  reportUpgrade({ root, from, to, system, changed, retired, added, overrides, pinned, droppedBlocks })
 }
 
-module.exports = { copyTemplate, scaffold, providerNames, adviceFor, upgrade, destroy, PROJECT_ROOT }
+module.exports = { copyTemplate, scaffold, providerNames, upgrade, destroy, PROJECT_ROOT }

package/engine/cli/planning.js

@@ -77,6 +77,7 @@ function check(dir, cli) {
   errors.push(...integration.errors)
   warnings.push(...integration.warnings)
 
+  warnings.push(...PC.competingSections(root))
   // 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, '..'))) {

package/engine/cli/upgrade-report.js

@@ -0,0 +1,150 @@
+'use strict'
+
+// Lo que `upgrade` le dice a quien lo corrió: qué hacer en vez de haber editado, y qué le pasó a la
+// instancia. Vive aparte del ciclo de vida porque su reloj es el de lo que hay para decir —la frontera
+// de propiedad, la redacción de un consejo, cada versión que agrega o retira algo— y no el del
+// procedimiento que lo hace. Y porque así se prueba sin tocar el disco.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const O = require('../core/ownership')
+const M = require('../core/manifest')
+const CL = require('../core/changelog')
+
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
+
+// Qué hacer en vez de haber editado, según a quién pertenece cada archivo que se perdería.
+//
+// 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.
+// Qué le pasó a la instancia en esta actualización, contado a quien la corrió. Recibe el resultado
+// entero en vez de recalcular nada: lo que se informa es exactamente lo que ocurrió.
+function reportUpgrade({ root, from, to, system, changed, retired, added, overrides, pinned, droppedBlocks }) {
+  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`)
+  // Nombrarlos importa tanto como crearlos: existen para que los completes, y uno que aparece sin
+  // aviso no lo completa nadie.
+  for (const relative of added) console.log(`+ ${relative}: lo agrega esta versión, completalo`)
+  // 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` 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.
+  if (fs.existsSync(path.join(root, '.ops', 'engine'))) {
+    console.log('\n⚠ esta instancia tiene el motor vendorizado en .ops/, que Cauce ya no distribuye.')
+    console.log('  Corré "npm install" para tenerlo como dependencia y después borrá .ops/ a mano.')
+  }
+  // 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.
+  for (const { runner, relative } of droppedBlocks) {
+    console.log(`− ${relative}: se reemplazó entero y con él las instrucciones de ${runner}`)
+  }
+  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}`)
+  }
+  // Después de aplicar, no antes: recién acá el paquete tiene la versión nueva y la comparación dice
+  // algo. Es además el momento en que alguien está mirando qué le trajo la actualización.
+  const FK = require('../agents/fork')
+  for (const entry of FK.drift(root)) console.log(`  ⚠ ${FK.driftLine(entry)}`)
+}
+
+// Qué trae la versión nueva, leído del paquete: sin esto el reemplazo de system/ es a ciegas.
+function printChangelog(from, to) {
+  const notes = CL.between(CL.read(PROJECT_ROOT), from, to)
+  if (!notes.length) return
+  for (const note of notes) {
+    console.log(`\n  ── ${note.version} ──`)
+    for (const line of note.body.split('\n')) if (line.trim()) console.log(`  ${line}`)
+  }
+  console.log('')
+}
+
+// Mirar sin tocar: qué traería la actualización y qué se perdería si se aplicara. Devuelve el código de
+// salida en vez de cortar el proceso, para que el corte se vea donde se decide.
+//
+// Lo editado localmente va 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.
+function previewUpgrade({ from, to, changed }) {
+  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`)
+    // 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')
+    return changed.length ? 1 : 0
+  }
+  // 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
+  // contrario: no lo que se gana, sino lo que se deja.
+  if (CL.compare(to, from) < 0) {
+    console.log(`↩ volvés a ${to} desde ${from}. Esto es lo que dejás de tener:`)
+    printChangelog(to, from)
+  } else {
+    console.log(`⚠ hay una versión más nueva: ${to} (la instancia tiene ${from || 'una previa'})`)
+    printChangelog(from, to)
+  }
+  return 1
+}
+
+module.exports = { adviceFor, previewUpgrade, reportUpgrade }

package/engine/integrations/registry.js

@@ -131,10 +131,14 @@ function validate(root, onlyProvider = '') {
       if (typeof snapshot.sync.missingFromRemote !== 'boolean') {
         errors.push(`${at}: missingFromRemote debe ser boolean`)
       }
-      const actualDraftChanged = sha256(draft) !== snapshot.sync.draftBaseHash
-      if (snapshot.sync.draftBaseHash && snapshot.sync.draftChanged !== actualDraftChanged) {
-        errors.push(`${at}: draftChanged no coincide con el contenido real`)
-      }
+      // `draftChanged` no se valida contra el contenido, y es deliberado: el README manda curar el draft
+      // a mano y ese camino no recalcula el flag, así que exigir la coincidencia ponía en rojo el paso
+      // siguiente del recorrido documentado, todas las veces.
+      //
+      // Lo que se perdería sería una señal que no existe. El campo se escribe en `sync`, `rebase` y
+      // `reconcile`, y se leía en un solo lugar: esta comprobación, que lo comparaba consigo mismo
+      // recalculado. Lo que decide qué vuelve al remoto es `S.derive`, que compara el contenido contra
+      // la base y nunca lo consulta. Un derivado que se puede recalcular no es un error de validación.
       const signals = S.derive(snapshot, draft)
       if (snapshot.sync.role === 'context' && fields.state !== 'context') {
         errors.push(`${at}: context exige state=context`)
@@ -324,8 +328,8 @@ function promote(root, name, key) {
     const target = path.join(roadmap, recovered || `epic-${num}-${slug}.md`)
     const content = `---\nepic: ${num}\ntitle: ${sections.title}\nstatus: open\n` +
       `service: ${fields.service}\nsource: ${name}\nremote: ${key}\n---\n\n` +
-      `# Épica ${num} — ${sections.title}\n\n## Resultado\n\n${sections.Descripción}\n\n` +
-      `## Criterios\n\n- **C1** — ${oneLine(sections.Aceptación)}\n\n` +
+      `# Épica ${num} — ${sections.title}\n\n## Resultado\n\n${nestHeadings(sections.Descripción)}\n\n` +
+      `## Criterios\n\n- **C1** — ${criterionText(sections.Aceptación)}\n\n` +
       `## Contexto relevante\n\n- Importado desde ${name}:${key}; validar rutas del servicio antes de activar.\n\n` +
       `## Historias\n\n- [ ] **${slug}** (→ C1) — ${oneLine(sections.title)}. ` +
       `(service: ${fields.service})\n`
@@ -383,6 +387,17 @@ const slugify = (value) => String(value).normalize('NFD').replace(/[\u0300-\u036
   .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 70)
 const oneLine = (value) => String(value).replace(/\s+/g, ' ').trim()
 
+// La descripción remota entra dentro de `## Resultado`, y trae sus propios encabezados: el fixture del
+// propio toolkit trae `## Criterios de aceptación`. En el mismo nivel compiten con las secciones que
+// escribe la épica, y el parser toma la primera que case: leía la importada, que no tiene ninguna
+// viñeta `- **CN** —`, y `check` rechazaba la épica recién promovida. Bajarlos un nivel los deja
+// legibles y fuera de la competencia, y cubre igual un `## Historias` o un `## Resultado` remotos.
+const nestHeadings = (text) => String(text).replace(/^(#{1,5})\s+/gm, '#$1 ')
+
+// El texto de un criterio importado, sin el guión de la viñeta de la que salió: sin esto el criterio
+// quedaba escrito `- **C1** — - La fecha…`, con los dos guiones pegados.
+const criterionText = (value) => oneLine(String(value).replace(/^\s*[-*]\s+/, ''))
+
 // En cuál de tres estados está el proveedor: `ready`, `incomplete` o `unreadable`. Lee su propio
 // `config.json`, que es donde vive la decisión, y no el registro: un proveedor listado y apagado no es
 // un proveedor disponible.
@@ -398,6 +413,8 @@ function providerState(root, name) {
 module.exports = {
   providerState,
   adapter,
+  criterionText,
+  nestHeadings,
   frontmatter,
   promote,
   providerConfig,

package/engine/planning/contracts.js

@@ -177,6 +177,31 @@ function ruleIds(file) {
 // 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á.
+// Dos secciones de una épica que compiten por el mismo rol. El parser prefiere la exacta, así que
+// resuelve —y en silencio: quien escribió las dos no se entera de que una se ignora entera. La
+// promoción dejó de generarlas cuando lo importado empezó a bajar un nivel; a mano se siguen pudiendo
+// escribir, y ahí el aviso es lo único que lo dice.
+function competingSections(dir) {
+  const roadmap = path.join(dir, 'roadmap')
+  const avisos = []
+  let files = []
+  try { files = fs.readdirSync(roadmap).filter((file) => /^epic-\d{3}-/.test(file)) } catch { return [] }
+  for (const file of files.sort()) {
+    const text = P.read(path.join(roadmap, file))
+    const titles = [...text.matchAll(/^##\s+(.+)$/gm)].map((hit) => hit[1].trim())
+    for (const role of [/Criterios/i, /Historias/i]) {
+      const casan = titles.filter((title) => role.test(title))
+      if (casan.length < 2) continue
+      const exact = new RegExp(`^${role.source}$`, role.flags)
+      const gana = casan.find((title) => exact.test(title)) || casan[0]
+      const ignoradas = casan.filter((title) => title !== gana)
+      avisos.push(`roadmap/${file}: "## ${gana}" convive con "## ${ignoradas.join('", "## ')}"; `
+        + 'sólo se lee la primera y el resto se ignora entero')
+    }
+  }
+  return avisos
+}
+
 function retiredByOverride(dir, name) {
   const rules = path.join(dir, 'rules')
   const system = path.join(rules, 'system', name)
@@ -432,6 +457,7 @@ module.exports = {
   validateAdr,
   validateRules,
   retiredByOverride,
+  competingSections,
   validateBacklogStructure,
   validCommitTrace,
   validDecisionTrace,

package/engine/planning/parser.js

@@ -46,9 +46,17 @@ function frontmatter(text) {
   return (key) => values[key] || ''
 }
 
+// La coincidencia exacta gana sobre la parcial, y sólo si no hay exacta se acepta la parcial. Con
+// `find` a secas, `## Criterios de aceptación` le ganaba a `## Criterios` por estar antes: la épica que
+// promovía una integración traía la sección importada primero y el parser leía esa, que no tiene
+// ninguna viñeta `- **CN** —`. Anclar del todo habría roto lo contrario —`## Historias (Tareas)` es un
+// título real de una migración—, así que la parcial sigue valiendo cuando es la única.
 function section(text, heading) {
   const parts = text.split(/^##\s+/m)
-  return parts.find((part) => heading.test(part.split('\n')[0])) || ''
+  const titles = parts.map((part) => part.split('\n')[0].trim())
+  const exact = parts.findIndex((part, i) => new RegExp(`^${heading.source}$`, heading.flags).test(titles[i]))
+  if (exact >= 0) return parts[exact]
+  return parts.find((part, i) => heading.test(titles[i])) || ''
 }
 
 function withoutComments(text) {

package/package.json

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