@ingeniomaps/cauce 0.34.0 → 0.35.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.35.0] - 2026-08-19
+
+### Añadido
+
+- **`ops destroy <ops-root>`: sacar una instancia entera, en un comando.** Enumera qué se pierde
+  —épicas, cola, trabajo terminado con su evidencia, acciones humanas pendientes, el contexto escrito— y
+  para. Sólo un segundo intento con `--force` desinstala cada runner cableado y después borra la
+  instancia. El orden no es negociable: borrar la carpeta antes que el wiring deja al runner ejecutando
+  guards que ya no existen, que es exactamente lo que pasaba haciéndolo a mano. También como
+  `make destroy`, que muestra el resumen sin borrar.
+
+### Corregido
+
+- **Una épica que nadie va a leer deja de pasar por válida.** Una corrida real escribió
+  `roadmap/epic-001.md`, sin slug: el parser busca `epic-NNN-<slug>.md`, así que `check` respondía
+  «planning válido: 0 épica(s)» con la épica ahí, y `autobuild` nunca habría encontrado trabajo en ella.
+  Renombrarla destapó dos errores que el silencio tapaba —un `status` inválido y un criterio sin historia
+  que lo cubriera—. Ahora cualquier archivo del roadmap que se llame como una épica y el parser no vaya a
+  leer es un error que dice cómo nombrarlo.
+
+- **`check` avisa cuando una dimensión del molde desapareció de `organization/`.** Un agente que reescribe
+  esos archivos se queda con el contenido y pierde la estructura: el resultado se lee entero y completo, y
+  la dimensión que falta no la va a reclamar nadie. Va como advertencia —esos archivos son de la empresa y
+  reestructurarlos a propósito es legítimo—, y agregar secciones propias no dice nada.
+
+- **Volver a una versión anterior deja de anunciarse como una actualización.** `upgrade --check` decía
+  «hay una versión más nueva: 0.33.0» contra una instancia en 0.34.0. Ahora dice que volvés, y te imprime
+  las entradas que dejás de tener en vez de las que ganarías.
+
+### Cambiado
+
+- **Los runners sin recorrido ejecutable llevan una lista de salida.** Codex, Gemini y Antigravity operan
+  el arranque leyendo instrucciones, y una corrida real falló cinco puntos de una vez: preguntas en
+  formulario, una épica sin slug, `organization/` reestructurado, `HUMAN_ACTIONS.md` vacío y `ops` listado
+  como servicio del producto. Todos del mismo lado: lo que no deja un archivo visible. La lista dice qué
+  se comprueba mirando el disco, que es lo que la prosa pidiendo cuidado no consigue.
+
 ## [0.34.0] - 2026-08-19
 
 ### Añadido

package/README.md

@@ -177,6 +177,7 @@ Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contr
 | `ops tree <planning>` | Muestra roadmap, backlog, WIP, inbox y done sin mutar nada. |
 | `ops context <planning>` | Emite el contexto mínimo de la tarea vigente para un runner. |
 | `ops upgrade <ops-root>` | Actualiza `system/` y el runtime sin tocar lo del proyecto. |
+| `ops destroy <ops-root>` | Enumera qué se pierde y, con `--force`, saca wiring e instancia. |
 | `ops archive <planning> <NNN>` | Archiva el DONE de una épica cerrada de forma idempotente. |
 | `ops agents list [ops-root]` | Lista los cargos visibles resolviendo la precedencia. |
 | `ops agents fork <cargo>` | Copia un cargo del catálogo a la empresa, que pasa a mantenerlo. |
@@ -301,7 +302,10 @@ La instalación fusiona la configuración propia del runner y conserva las entra
 reemplaza los guards que el propio toolkit había registrado sueltos por el grupo que ahora los cubre, y
 lista cuáles quitó. Nada que no haya escrito el toolkit se toca.
 
-Para sacarlo, `automation uninstall` quita exactamente lo que Cauce entregó y sigue igual que como lo
+Para sacar una instancia entera —wiring incluido— está `ops destroy`, que primero enumera qué se pierde
+y sólo borra si se lo repite con `--force`: el orden importa, porque borrar la carpeta antes que el
+wiring deja al runner ejecutando guards que ya no existen. Para sacar sólo el wiring y conservar la
+instancia, `automation uninstall` quita exactamente lo que Cauce entregó y sigue igual que como lo
 entregó: los guards de la configuración del runner, los workflows, los punteros a cargos. Lo que no
 escribió —tus hooks, tus workflows, tus skills— queda donde está, y un archivo suyo que hayas editado se
 conserva y se nombra en la salida. Borrar la carpeta ops sin esto deja al runner ejecutando guards que ya

package/automatization/runners/antigravity/skills/onboard/SKILL.md

@@ -38,7 +38,27 @@ El arranque tiene tres objetivos y ninguno más: entender qué es el proyecto, d
 para él y que la primera tarea pueda empezar. El análisis profundo viene después, cuando la persona pida
 algo concreto.
 
-Cerrá escribiendo `epic-001` en `{{OPS_DIR}}planning/roadmap/`: su resultado es que una tarea pueda
+Cerrá escribiendo la épica en `{{OPS_DIR}}planning/roadmap/`: su resultado es que una tarea pueda
 atravesar el ciclo entero, y sus criterios salen de lo que hoy falta —contexto sin supuestos, cada
-comando en verde, el guard de límites probado en las dos direcciones, una tarea piloto en DONE—. Validá
-con `node {{OPS_DIR}}tools/ops.js check planning`. **Nunca promuevas al BACKLOG**: esa firma es humana.
+comando en verde, el guard de límites probado en las dos direcciones, una tarea piloto en DONE—.
+**Nunca promuevas al BACKLOG**: esa firma es humana.
+
+## Antes de decir que terminaste
+
+Esta lista no es un resumen de lo de arriba: es lo que se comprueba mirando el disco. Una corrida real
+falló los cinco puntos sin darse cuenta, y todos del mismo lado —lo que no produce un archivo visible—.
+
+1. **Una pregunta por vez.** Si mandaste dos o más juntas, numeradas, hiciste un formulario. La segunda
+   pregunta depende de la primera respuesta: por eso se hacen de a una.
+2. **`epic-NNN-<slug>.md`**, con slug en el nombre y `status: open`. `epic-001.md` no lo lee nadie: ni
+   `check`, ni `tree`, ni el runner que busca trabajo. Existe y no existe a la vez.
+3. **Las secciones de `{{OPS_DIR}}organization/` son las del molde.** Escribí adentro de ellas; agregá las tuyas
+   abajo si hacen falta. Reemplazar la estructura pierde dimensiones que nadie va a reclamar después,
+   porque el archivo se lee completo.
+4. **`HUMAN_ACTIONS.md` tiene filas.** Una por credencial nombrada en el inventario, una por sistema
+   externo o MCP, una por la autoridad de push. Si quedó vacío, no es que no hubiera nada: es que lo que
+   no te corresponde se perdió en vez de quedar escrito para alguien.
+5. **`ops` no es un servicio del producto.** No va en el mapa real: es la instancia desde la que trabajás.
+
+Recién ahí, `node {{OPS_DIR}}tools/ops.js check planning`. Si sale con advertencias, leelas: son
+exactamente estas cosas.

package/automatization/runners/codex/AGENTS.md

@@ -53,6 +53,12 @@ El arranque tiene tres objetivos y ninguno más: entender qué es el proyecto, d
 para él y que la primera tarea pueda empezar. El análisis profundo viene después, cuando la persona pida
 algo concreto.
 
+Antes de darlo por terminado, comprobá cinco cosas mirando el disco: preguntaste de a una y no en
+formulario; la épica se llama `epic-NNN-<slug>.md` con `status: open` —`epic-001.md` no lo lee nadie—;
+las secciones de `{{OPS_DIR}}organization/` siguen siendo las del molde y lo tuyo se agregó adentro;
+`{{OPS_DIR}}planning/HUMAN_ACTIONS.md` tiene una fila por credencial, por externo y por la autoridad de
+push; y `ops` no figura como servicio del producto en el mapa.
+
 ## Los equipos
 
 Un equipo es una secuencia de cargos con etapas y exit gates, para evaluar una intención antes de que

package/automatization/runners/gemini/GEMINI.md

@@ -46,6 +46,12 @@ El arranque tiene tres objetivos y ninguno más: entender qué es el proyecto, d
 para él y que la primera tarea pueda empezar. El análisis profundo viene después, cuando la persona pida
 algo concreto.
 
+Antes de darlo por terminado, comprobá cinco cosas mirando el disco: preguntaste de a una y no en
+formulario; la épica se llama `epic-NNN-<slug>.md` con `status: open` —`epic-001.md` no lo lee nadie—;
+las secciones de `{{OPS_DIR}}organization/` siguen siendo las del molde y lo tuyo se agregó adentro;
+`{{OPS_DIR}}planning/HUMAN_ACTIONS.md` tiene una fila por credencial, por externo y por la autoridad de
+push; y `ops` no figura como servicio del producto en el mapa.
+
 Nunca omitas aprobaciones, inventes credenciales, escribas remoto, hagas push/deploy o promociones
 trabajo desde INBOX.
 

package/engine/cli/args.js

@@ -20,6 +20,7 @@ const FLAGS = {
   tree: ['--json', '--no-color'],
   context: ['--json'],
   upgrade: ['--check', '--force'],
+  destroy: ['--force'],
   archive: [],
   agents: ['--json', '--own', '--system'],
   integration: ['--fixture'],

package/engine/cli/ops.js

@@ -47,6 +47,7 @@ function usage() {
   ops tree <planning-dir> [--no-color] [--json]
   ops context <planning-dir> [--json]
   ops upgrade <ops-root> [--check] [--force]
+  ops destroy <ops-root> [--force]
   ops archive <planning-dir> <NNN>
   ops integration list <ops-root>
   ops integration enable <ops-root> <provider>
@@ -440,6 +441,30 @@ function onboard(rootArg, cli, runner = '') {
   console.log('  Con tus respuestas escribe organization/, el mapa real de AGENTS.md y la primera épica.')
 }
 
+// Qué dimensiones enumera el molde de `organization/` y cuáles dejaron de estar. Un agente que reescribe
+// esos archivos tiende a quedarse con el contenido y perder la estructura: el resultado se lee entero y
+// completo, y nadie va a pedir después la dimensión que falta porque nada indica que faltaba.
+//
+// Va como advertencia y no como error: la empresa es dueña de esos archivos y puede reestructurarlos a
+// propósito. Lo que no puede pasar es que una dimensión desaparezca sin que se vea.
+function seccionesPerdidas(root) {
+  const avisos = []
+  const molde = path.join(PROJECT_ROOT, 'template', 'organization')
+  for (const name of ['company.md', 'product.md']) {
+    const propio = path.join(root, 'organization', name)
+    if (!fs.existsSync(propio) || !fs.existsSync(path.join(molde, name))) continue
+    const titulos = (text) => new Set((text.match(/^##\s+(.+)$/gm) || []).map((line) => line.trim()))
+    const esperadas = titulos(fs.readFileSync(path.join(molde, name), 'utf8'))
+    const presentes = titulos(fs.readFileSync(propio, 'utf8'))
+    const faltan = [...esperadas].filter((titulo) => !presentes.has(titulo))
+    if (!faltan.length) continue
+    // Reescrito entero, faltan todas: enumerarlas hace una línea ilegible y el número dice más.
+    const lista = faltan.length > 3 ? `${faltan.slice(0, 3).join(', ')} y ${faltan.length - 3} más` : faltan.join(', ')
+    avisos.push(`organization/${name}: sin ${lista} — el molde las trae y acá no están`)
+  }
+  return avisos
+}
+
 function check(dir, cli) {
   const root = path.resolve(dir || '.')
   const errors = []
@@ -552,6 +577,8 @@ function check(dir, cli) {
   const FK = require('../agents/fork')
   for (const entry of FK.drift(path.resolve(root, '..'))) warnings.push(FK.driftLine(entry))
 
+  warnings.push(...seccionesPerdidas(path.resolve(root, '..')))
+
   if (cli.has('--json')) {
     console.log(JSON.stringify({
       ok: !errors.length,
@@ -732,6 +759,76 @@ function instanceVersion(root) {
   } catch { return '' }
 }
 
+// Qué se pierde al borrar una instancia. Se cuenta antes de tocar nada porque es lo único que vuelve
+// reversible la decisión: quien lee esto todavía puede no seguir.
+// Lo cuenta el mismo parser que usan `check` y `tree`, no una expresión regular propia: los moldes traen
+// ejemplos comentados, y contarlos a mano anunciaba una tarea en cola y otra terminada en una instancia
+// recién creada. Un aviso que exagera lo que se pierde se deja de leer igual que uno que lo minimiza.
+function loQueSePierde(root) {
+  const planning = path.join(root, 'planning')
+  const cola = P.readBacklog(planning).reduce((total, hito) => total + (hito.tasks || []).length, 0)
+  const acciones = (() => {
+    try {
+      const texto = fs.readFileSync(path.join(planning, 'HUMAN_ACTIONS.md'), 'utf8')
+      return (texto.match(/^\| (?!Tarea|---)/gm) || []).length
+    } catch { return 0 }
+  })()
+  return {
+    epicas: P.readEpics(planning).length,
+    hechas: (P.readDone(planning).entries || []).length,
+    enCola: cola,
+    acciones,
+    contexto: !OB.guide(root).fresh,
+    runners: [...new Set(Object.keys(M.readRunners(root)).map((key) => key.split('/')[0]))],
+  }
+}
+
+// Saca la instancia entera y el wiring que dejó en cada runner. Existe porque la alternativa era una
+// lista de pasos a mano —desinstalar cada runner y después `rm -rf`—, y una lista se ejecuta a medias:
+// el orden importa, y borrar primero la carpeta deja al runner ejecutando guards que ya no existen.
+//
+// Nunca borra sin que alguien lo haya pedido dos veces. Lo que hay adentro —planning, organization, la
+// evidencia de lo hecho— es del proyecto y no lo repone ningún `init`.
+function destroy(dir, cli) {
+  const root = path.resolve(dir || '.')
+  if (!fs.existsSync(path.join(root, 'ops.config.json'))) {
+    fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, 2)
+  }
+  if (O.mode(root) === 'toolkit') fail(`${root} es el toolkit: acá se fabrica Cauce, no se lo borra.`, 2)
+
+  const perdida = loQueSePierde(root)
+  const lineas = [
+    perdida.epicas && `${perdida.epicas} épica(s) en el roadmap`,
+    perdida.enCola && `${perdida.enCola} tarea(s) en la cola`,
+    perdida.hechas && `${perdida.hechas} tarea(s) terminada(s) con su evidencia`,
+    perdida.acciones && `${perdida.acciones} acción(es) humana(s) pendiente(s)`,
+    perdida.contexto && 'el contexto escrito en organization/',
+  ].filter(Boolean)
+
+  if (!cli.has('--force')) {
+    console.log(`Borrar ${root} se lleva:`)
+    for (const linea of lineas) console.log(`  − ${linea}`)
+    if (!lineas.length) console.log('  − nada escrito todavía: la instancia está como salió de init')
+    if (perdida.runners.length) {
+      console.log(`  y saca el wiring de: ${perdida.runners.join(', ')} (lo tuyo queda donde está)`)
+    }
+    console.log('\nNada de esto lo repone un init. Si es lo que querés: repetí con --force.')
+    process.exit(1)
+  }
+
+  for (const runner of perdida.runners) {
+    try { A.uninstall(root, runner, console) } catch (error) { console.error(`  ${runner}: ${error.message}`) }
+  }
+  // El orden no es negociable: primero el wiring, después la carpeta. Al revés, cada llamada de
+  // herramienta del runner queda ejecutando un guard que ya no está.
+  const adentro = process.cwd() === root || process.cwd().startsWith(`${root}${path.sep}`)
+  fs.rmSync(root, { recursive: true, force: true })
+  console.log(`✓ ${root} borrado`)
+  // Correrlo desde adentro es lo natural —ahí está `tools/ops.js`— y deja la terminal en un directorio
+  // que ya no existe: el próximo comando falla con un `getcwd` que no dice nada de esto.
+  if (adentro) console.log('  tu terminal quedó en esa carpeta: hacé "cd .." antes del próximo comando.')
+}
+
 // 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) {
@@ -760,8 +857,16 @@ function upgrade(dir, cli) {
       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')
     }
-    console.log(`⚠ hay una versión más nueva: ${to} (la instancia tiene ${from || 'una previa'})`)
-    printChangelog(from, to)
+    // 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)
+    }
     for (const file of changed) console.log(`  editado localmente: ${file}`)
     process.exit(1)
   }
@@ -1263,6 +1368,7 @@ async function run(cli) {
   else if (command === 'tree') tree(arg[1], cli)
   else if (command === 'context') context(arg[1], cli)
   else if (command === 'upgrade') upgrade(arg[1], cli)
+  else if (command === 'destroy') destroy(arg[1], cli)
   else if (command === 'agents') agents(arg[1], arg[2], arg[3], cli)
   else if (command === 'archive') archive(arg[1], arg[2])
   else if (command === 'integration') {

package/engine/planning/contracts.js

@@ -64,6 +64,16 @@ function validateRoadmapStructure(dir) {
   try { entries = fs.readdirSync(roadmap, { withFileTypes: true }) } catch { return ['falta roadmap/'] }
   const errors = []
   for (const entry of entries) {
+    // Un archivo que se llama como una épica y no cumple el patrón no lo lee nadie: ni `check`, ni
+    // `tree`, ni el runner que busca trabajo. Ignorarlo en silencio es peor que rechazarlo, porque el
+    // planning se reporta válido mientras la épica que alguien escribió no existe para el sistema.
+    if (/^epic-/.test(entry.name) && !/^epic-\d{3}-/.test(entry.name)) {
+      errors.push(
+        `roadmap/${entry.name}: nadie lo lee. Una épica se nombra epic-NNN-<slug>.md, `
+        + 'o un directorio epic-NNN-<slug>/ con spec.md adentro.',
+      )
+      continue
+    }
     if (!entry.isDirectory() || !/^epic-\d{3}-/.test(entry.name)) continue
     const epicDir = path.join(roadmap, entry.name)
     if (!fs.existsSync(path.join(epicDir, 'spec.md'))) {

package/package.json

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

package/template/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-.PHONY: help check tree context upgrade automation-check
+.PHONY: help check tree context upgrade destroy automation-check
 .PHONY: integration-check integration-sync require-key integration-promote
 .PHONY: require-agent agent-learn agent-propose agent-evaluate require-team team-check team-show
 .PHONY: install-claude install-codex install-gemini install-antigravity
@@ -25,6 +25,9 @@ context: ## Muestra el contexto mínimo de la tarea vigente
 
 # `init` fija la versión exacta del motor, así que `npm update` no la mueve: hay que pedir @latest.
 # Sin este primer paso `upgrade` compara contra el motor instalado y contesta «al día» para siempre.
+destroy: ## Muestra qué se pierde al borrar esta instancia (borrar exige --force a mano)
+	@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
 	@node tools/ops.js upgrade .