@ingeniomaps/cauce 0.57.0 → 0.58.0

package/CHANGELOG.md

@@ -14,6 +14,21 @@ 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.58.0] - 2026-09-03
+
+### Corregido
+
+- **`upgrade` te trae los archivos propios que una versión agrega.** `upgrade` reemplaza lo del toolkit
+  y no toca lo tuyo, que es lo correcto — pero cuando una versión **agrega** un archivo del proyecto, la
+  instancia que actualiza no lo recibía nunca. Pasó con 0.57.0: `organization/workspace.md` llegaba a
+  una instancia nueva y no a una que actualizaba, que quedaba con un `AGENTS.md` nombrándolo tres veces
+  y el archivo sin existir. Ahora se crea y se dice: `+ organization/workspace.md: lo agrega esta
+  versión, completalo`.
+
+  **Lo que no hace, a propósito**: reponer cualquier archivo del molde que falte. Borrar uno que no usás
+  es legítimo y devolvértelo en cada actualización sería peor que el problema, así que se crea sólo lo
+  que cada versión declara que agrega. Lo que ya tenés no se pisa nunca.
+
 ## [0.57.0] - 2026-09-03
 
 ### Agregado

package/engine/cli/instance.js

@@ -381,6 +381,29 @@ function upgrade(dir, cli) {
     )
   }
 
+  // Lo que una versión agrega y es del proyecto: se crea si falta y nunca se pisa. `systemPaths` no lo
+  // 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 added = []
+  for (const relative of O.addedPaths()) {
+    const target = path.join(root, relative)
+    if (fs.existsSync(target)) continue
+    const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
+    if (!fs.existsSync(origin)) continue
+    F.assertNoSymlinkPath(root, target)
+    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),
+      '{{MODE}}': O.mode(root),
+      '{{WORKSPACE_PATH}}': O.mode(root) === 'embedded' ? '.' : '..',
+    })) content = content.replaceAll(key, value)
+    F.atomicWrite(target, content)
+    added.push(relative)
+  }
+
   for (const relative of [...system, ...O.RUNTIME_PATHS]) {
     const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
     if (!fs.existsSync(origin)) continue
@@ -433,6 +456,9 @@ function upgrade(dir, cli) {
   // 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')

package/engine/core/ownership.js

@@ -171,6 +171,52 @@ function overrides(root) {
 
 // Rutas que el toolkit dejó de materializar. Sin esto una instancia arrastra para siempre lo que
 // alguna versión suya copió: `upgrade` agrega y reemplaza, pero nunca quitaba nada.
+// Cada archivo propio del molde, con cómo llega a una instancia que **ya existe**. `upgrade` sólo
+// reemplaza lo del sistema y el runtime, así que un archivo del proyecto no llega por ninguna otra vía:
+// o toda instancia lo tiene desde su `init` —`init`— o una versión lo agrega y hay que crearlo
+// —`upgrade`—. Es el simétrico de `RETIRED`, que dice qué dejamos de distribuir.
+//
+// Se declara archivo por archivo en vez de copiar del molde todo lo que falte, y la diferencia importa:
+// borrar un archivo del molde que no se usa es legítimo —`check` da verde sin él— y reponerlo en cada
+// actualización sería la fricción recurrente que sacar `AGENTS.md` de las manos del proyecto vino a
+// evitar. En disco «lo borré» y «nunca llegó» se ven igual, y para un archivo del proyecto no hay
+// registro que los separe: el manifiesto anota lo que entrega el toolkit.
+//
+// La puerta compara estas claves contra el árbol del molde, así que agregar un archivo allá obliga a
+// decidir acá. Una entrada pasa de `upgrade` a `init` cuando ninguna versión soportada puede no
+// tenerlo; que se quede de más no rompe nada, porque el archivo ya está y se conserva.
+const TEMPLATE_OWN = {
+  'README.md': 'init',
+  'gitignore': 'init',
+  'integrations/config.json': 'init',
+  'integrations/jira/README.md': 'init',
+  'integrations/jira/config.json': 'init',
+  'integrations/jira/proposed/README.md': 'init',
+  'integrations/jira/staging/.gitkeep': 'init',
+  'integrations/jira/staging/README.md': 'init',
+  'ops.config.json': 'init',
+  'organization/company.md': 'init',
+  'organization/domains.md': 'init',
+  'organization/product.md': 'init',
+  // 0.57.0. `AGENTS.md` lo nombra tres veces y se reemplaza en cada actualización, así que sin esto
+  // una instancia que actualiza queda leyendo una instrucción que apunta a un archivo que no tiene.
+  'organization/workspace.md': 'upgrade',
+  'planning/BACKLOG.md': 'init',
+  'planning/DONE.md': 'init',
+  'planning/HUMAN_ACTIONS.md': 'init',
+  'planning/INBOX.md': 'init',
+  'planning/WIP.md': 'init',
+  'planning/delivery/project.md': 'init',
+  'planning/done/.gitkeep': 'init',
+  'planning/reports/README.md': 'init',
+}
+
+// Lo que `upgrade` crea si falta, derivado de la declaración de arriba para que no haya dos listas que
+// puedan decir cosas distintas.
+function addedPaths() {
+  return Object.entries(TEMPLATE_OWN).filter(([, via]) => via === 'upgrade').map(([file]) => file)
+}
+
 const RETIRED = [
   'agents/roles/system',
   'flows/system',
@@ -248,6 +294,8 @@ function localChanges(root) {
 
 module.exports = {
   RETIRED,
+  TEMPLATE_OWN,
+  addedPaths,
   trackedPaths,
   packageDir,
   RUNTIME_PATHS,

package/package.json

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