@ingeniomaps/cauce 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -8,6 +8,33 @@ esa operación sea confiable en vez de sólo cómoda: acá se lee qué cambió a
 un cambio en el protocolo, en las reglas del sistema o en un guard es visible para el usuario y sube
 minor aunque no toque una sola línea de código.
 
+## [0.17.0] - 2026-08-16
+
+### Agregado
+
+- **`ops agents fork <cargo>`: una empresa se lleva un cargo del catálogo y lo mantiene desde su
+  carpeta.** El tercer camino ya resolvía —un cargo propio con el mismo slug tapa al del sistema, en el
+  listado, en `learn` y en el puntero que instala el runner—, pero llegar hasta ahí era copiar a mano, y
+  eso sale mal de una forma que no se nota: se agarra el `SKILL.md`, que es lo que se ve, y quedan atrás
+  los casos adversariales, las fuentes y el modelo operativo. El cargo responde igual y ya no se puede
+  evaluar, sin ningún aviso.
+
+  No se heredan los informes de aprendizaje, las propuestas ni los veredictos de evaluación. Un veredicto
+  pertenece al contrato que lo ganó, y el fork nace para dejar de ser ese contrato; una propuesta
+  pendiente arrastraría a la empresa a firmar una decisión que era nuestra.
+
+  En el toolkit se niega: acá el catálogo se edita, no se lo copia. Dejarlo pasar creaba un duplicado que
+  tapaba al original, y el trabajo siguiente se hacía sobre la copia mientras la versión que se publica
+  quedaba quieta.
+
+- **`check` y `upgrade` avisan cuando el cargo que forkeaste mejoró río arriba.** El mecanismo ya existía
+  para ADRs y reglas —«sobrescribir es legítimo; lo que no puede pasar es que ocurra en silencio»— pero
+  no cubría los cargos, que es donde más caro sale: un fork se hace una vez y se olvida.
+
+  Se compara contra los digests guardados al forkear, nunca contra la copia: la copia está editada a
+  propósito, así que medir contra ella devolvería «todo cambió» desde el primer ajuste. Editar lo propio
+  no dispara nada, y esa mitad es la que decide si el aviso se lee o se ignora.
+
 ## [0.16.1] - 2026-08-16
 
 ### Corregido

package/README.md

@@ -74,6 +74,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 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. |
 | `ops upgrade <ops-root>` | Actualiza `system/` y el runtime sin tocar lo del proyecto. |
 | `ops archive <planning> <NNN>` | Archiva el DONE de una épica cerrada de forma idempotente. |
 | `ops learn <agent>` | Prepara el informe semanal que completa la automatización de Codex. |
@@ -183,6 +184,25 @@ todas las empresas: investigarla una vez y bien es mejor que repetirla en cada i
 Por eso `learn` falla si lo corrés sobre un cargo del catálogo dentro de una instancia: escribiría en
 el paquete y se perdería. El ciclo mensual de aprendizaje tampoco se distribuye — vive sólo acá.
 
+#### Quedarse con una versión propia de un cargo del catálogo
+
+```bash
+npm run ops -- agents fork product-manager
+```
+
+Copia el cargo entero a `agents/roles/<slug>/` y desde ahí lo mantenés vos: `learn`, `evaluate` y el
+puntero que instala el runner pasan a resolver contra tu copia. **Copiarlo a mano no es equivalente**
+—se agarra el `SKILL.md`, que es lo que se ve, y quedan atrás los casos, las fuentes y el modelo
+operativo: el cargo responde igual y ya no se puede evaluar—.
+
+Lo que no viaja son los informes de aprendizaje, las propuestas y los veredictos de evaluación. Un
+veredicto pertenece al contrato que lo ganó, y el fork nace para dejar de ser ese contrato.
+
+A partir de ahí tu copia deja de recibir las mejoras del catálogo, que es lo que elegiste, pero no en
+silencio: `check` y `upgrade` avisan cuando el original cambia río arriba. Editar tu propia copia no
+dispara nada — se compara contra lo que el catálogo tenía el día del fork, no contra lo que vos
+escribiste después.
+
 ### Versionado
 
 Como `upgrade` reemplaza `system/` sin pedir confirmación, un cambio en el protocolo, en una regla del

package/engine/agents/fork.js

@@ -0,0 +1,152 @@
+'use strict'
+
+// Llevarse un cargo del catálogo a la carpeta de la empresa para mantenerlo desde ahí.
+//
+// Existe porque copiar a mano sale mal de una forma que no se nota: quien copia agarra el `SKILL.md`
+// —que es lo que se ve— y deja atrás los casos adversariales, las fuentes de aprendizaje y el modelo
+// operativo. Queda un cargo que responde igual y ya no se puede evaluar, sin ningún aviso.
+//
+// **Qué no se hereda.** Los informes de aprendizaje, las propuestas y los veredictos de evaluación se
+// quedan en el catálogo. No es prolijidad: un veredicto pertenece al contrato que lo ganó, y el fork
+// nace para dejar de ser ese contrato. Heredarlos le daría a la copia una garantía que no rindió, y
+// una propuesta pendiente arrastraría a la empresa a firmar una decisión que era nuestra.
+//
+// Lo que sí se hereda entero es el contrato y todo lo que lo hace verificable: casos, conductas
+// esperadas, fuentes, automatización y referencias. La empresa recibe un cargo evaluable desde el
+// primer minuto, y a partir de ahí lo mantiene.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const catalog = require('./catalog')
+const manifest = require('../core/manifest')
+const ownership = require('../core/ownership')
+
+// Se comparan contra la ruta relativa dentro del cargo. `_template.md` sobrevive en las dos carpetas
+// porque es andamiaje del mecanismo, no un artefacto de nadie.
+function inherited(relative) {
+  if (/^learning\/(reports|proposals)\//.test(relative)) return path.basename(relative) === '_template.md'
+  if (relative.startsWith('evaluations/results/')) return false
+  return true
+}
+
+function tree(dir, prefix = '') {
+  const found = []
+  let list = []
+  try { list = fs.readdirSync(dir, { withFileTypes: true }) } catch { return found }
+  for (const entry of list) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name
+    if (entry.isDirectory()) found.push(...tree(path.join(dir, entry.name), relative))
+    else found.push(relative)
+  }
+  return found.sort()
+}
+
+// La misma resolución que usa todo lo demás —paquete primero, toolkit después— en vez de deducirla
+// del directorio del motor: la versión que interesa es la del catálogo del que sale la copia.
+function packageVersion(root) {
+  const file = ownership.packagePath(root, 'package.json')
+  if (!file) return ''
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')).version || '' } catch { return '' }
+}
+
+// La fila deja el límite por escrito: arriba, cómo llegó el contrato a ser lo que es —decisiones que
+// tomamos nosotros—; abajo, lo que decida la empresa. Sin ese renglón, la primera fila propia parece
+// continuación de una conversación ajena.
+function markHistory(target, slug, version, date) {
+  const file = path.join(target, 'learning', 'HISTORY.md')
+  if (!fs.existsSync(file)) return
+  const origen = version ? `del catálogo de Cauce ${version}` : 'del catálogo de Cauce'
+  const row = `| ${date} | — | Copiado ${origen} | — | ${slug} pasa a mantenerlo esta empresa |\n`
+  const content = fs.readFileSync(file, 'utf8')
+  fs.writeFileSync(file, content.endsWith('\n') ? content + row : `${content}\n${row}`)
+}
+
+// `date` entra por parámetro en vez de leerse acá: la salida tiene que ser reproducible en una prueba.
+function fork(root, slug, date) {
+  // En el toolkit no hay a quién copiarle: el catálogo se mantiene acá, directo. Dejarlo pasar creaba
+  // un duplicado en `agents/roles/` que tapaba al original, y el trabajo siguiente se hacía sobre la
+  // copia mientras la versión que se publica quedaba quieta.
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
+    if (config.mode === 'toolkit') {
+      throw new Error(`${slug} vive acá: en el toolkit se edita el catálogo, no se lo copia`)
+    }
+  } catch (error) { if (error instanceof Error && error.message.includes('vive acá')) throw error }
+
+  const found = catalog.find(root, slug)
+  if (!found.system) {
+    throw new Error(`${slug} ya lo mantiene esta empresa: ${path.relative(root, found.dir)}`)
+  }
+  const type = path.basename(path.dirname(path.dirname(found.dir)))
+  const target = path.join(root, 'agents', type, slug)
+  if (fs.existsSync(target)) throw new Error(`${path.relative(root, target)} ya existe`)
+
+  const files = tree(found.dir).filter(inherited)
+  if (!files.includes('SKILL.md')) throw new Error(`${slug} no tiene SKILL.md: no hay contrato que copiar`)
+
+  // El digest sale del origen, no de la copia. Es lo que el catálogo tenía al momento del fork, y es
+  // contra eso que después se responde «esto mejoró río arriba»; medirlo sobre la copia lo ataría a
+  // cualquier cosa que le hagamos acá —empezando por la fila de historial que se escribe abajo—.
+  const digests = {}
+  for (const relative of files) {
+    const from = path.join(found.dir, relative)
+    const to = path.join(target, relative)
+    fs.mkdirSync(path.dirname(to), { recursive: true })
+    fs.copyFileSync(from, to)
+    digests[relative] = manifest.digest(from)
+  }
+
+  const version = packageVersion(root)
+  markHistory(target, slug, version, date)
+
+  const forks = { ...manifest.readForks(root) }
+  forks[slug] = { type, version, files: digests }
+  manifest.write(root, null, null, forks)
+
+  return { slug, type, dir: target, files, version, skipped: tree(found.dir).filter((one) => !inherited(one)) }
+}
+
+// Qué cambió en el catálogo desde que la empresa se llevó su copia.
+//
+// El fork es legítimo y esperado —para eso está el comando—, pero deja de recibir las mejoras del
+// toolkit, y eso no puede pasar en silencio: la empresa decidió mantener un cargo, no quedarse sin
+// enterarse de que el original mejoró. Nadie va a comparar 14 archivos a mano en cada actualización.
+//
+// Se compara contra los digests guardados al forkear, nunca contra la copia: la copia está editada a
+// propósito, así que medir contra ella devolvería «todo cambió» desde el primer ajuste. Y el aviso no
+// dice qué hacer —integrar o no es decisión de la empresa—, sólo que hay algo que mirar.
+function drift(root) {
+  const forks = manifest.readForks(root)
+  const catalogDir = ownership.packageDir(root, 'agents')
+  const found = []
+  for (const [slug, record] of Object.entries(forks)) {
+    if (!record || !record.files) continue
+    const source = catalogDir ? path.join(catalogDir, record.type || 'roles', 'system', slug) : ''
+    if (!source || !fs.existsSync(source)) continue
+    const current = tree(source).filter(inherited)
+    const changed = []
+    const removed = []
+    for (const [relative, recorded] of Object.entries(record.files)) {
+      if (!current.includes(relative)) { removed.push(relative); continue }
+      if (manifest.digest(path.join(source, relative)) !== recorded) changed.push(relative)
+    }
+    const added = current.filter((relative) => !(relative in record.files))
+    if (changed.length || added.length || removed.length) {
+      found.push({ slug, version: record.version || '', changed, added, removed })
+    }
+  }
+  return found.sort((left, right) => left.slug.localeCompare(right.slug))
+}
+
+// Una línea por fork, para que `check` y `upgrade` digan lo mismo con las mismas palabras.
+function driftLine(entry) {
+  const parts = []
+  if (entry.changed.length) parts.push(`${entry.changed.length} archivo(s) cambiaron`)
+  if (entry.added.length) parts.push(`${entry.added.length} nuevo(s)`)
+  if (entry.removed.length) parts.push(`${entry.removed.length} retirado(s)`)
+  const desde = entry.version ? ` desde ${entry.version}` : ''
+  return `${entry.slug}: tu copia no recibe mejoras del catálogo y ahí${desde} ${parts.join(', ')}`
+}
+
+module.exports = { drift, driftLine, fork, inherited }

package/engine/cli/ops.js

@@ -51,6 +51,7 @@ function usage() {
   ops learn <agent> [--proposal]
   ops evaluate <agent> [--cases [--json]]
   ops agents list [ops-root] [--own|--system] [--json]
+  ops agents fork <cargo> [ops-root]
   ops team list
   ops team check <team>
   ops team show <team>`)
@@ -300,6 +301,9 @@ function check(dir) {
   for (const override of O.overrides(path.resolve(root, '..'))) {
     warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} (override explícito)`)
   }
+  // 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')
+  for (const entry of FK.drift(path.resolve(root, '..'))) warnings.push(FK.driftLine(entry))
 
   if (process.argv.includes('--json')) {
     console.log(JSON.stringify({
@@ -604,6 +608,10 @@ function upgrade(dir) {
   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)}`)
 }
 
 // Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
@@ -614,7 +622,22 @@ function opsRoot(dir) {
   return path.resolve(dir || process.env.OPS_ROOT || '.')
 }
 
-function agents(action, dir) {
+function agentsFork(slug, dir) {
+  const root = opsRoot(dir)
+  if (!slug) fail('Falta el cargo: ops agents fork <cargo> [ops-root]', 2)
+  let result
+  const date = new Date().toISOString().slice(0, 10)
+  try { result = require('../agents/fork').fork(root, slug, date) } catch (error) { fail(error.message, 2) }
+  console.log(`+ ${path.relative(root, result.dir)} (${result.files.length} archivo(s))`)
+  if (result.skipped.length) {
+    console.log(`  quedan en el catálogo: ${result.skipped.length} artefacto(s) que ganó su versión`)
+  }
+  console.log(`  copiado de Cauce ${result.version || '(versión desconocida)'}; desde ahora lo mantenés vos`)
+  console.log(`  reinstalá tu runner para que ${slug} apunte a tu copia`)
+}
+
+function agents(action, dir, extra) {
+  if (action === 'fork') return agentsFork(dir, extra)
   if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
   const root = opsRoot(dir)
   // Una empresa mantiene sus cargos, no los nuestros: `learn` sobre uno del catálogo se niega, así que
@@ -884,7 +907,7 @@ async function main() {
   else if (command === 'tree') tree(arg[1])
   else if (command === 'context') context(arg[1])
   else if (command === 'upgrade') upgrade(arg[1])
-  else if (command === 'agents') agents(arg[1], arg[2])
+  else if (command === 'agents') agents(arg[1], arg[2], arg[3])
   else if (command === 'archive') archive(arg[1], arg[2])
   else if (command === 'integration') {
     await integration(arg[1], arg[2], arg[3], arg[4])

package/engine/core/manifest.js

@@ -30,17 +30,24 @@ function readAll(root) {
     return {
       files: typeof data.files === 'object' && data.files ? data.files : {},
       runners: typeof data.runners === 'object' && data.runners ? data.runners : {},
+      forks: typeof data.forks === 'object' && data.forks ? data.forks : {},
     }
-  } catch { return { files: {}, runners: {} } }
+  } catch { return { files: {}, runners: {}, forks: {} } }
 }
 
 function read(root) { return readAll(root).files }
 
 function readRunners(root) { return readAll(root).runners }
 
+// Tercera sección, y de otra naturaleza que las dos anteriores: `files` y `runners` registran lo que
+// Cauce entregó, mientras `forks` registra lo que la empresa se llevó. Guarda el contenido del cargo
+// del sistema **en el momento de la copia**, que es lo único contra lo que se puede decir después
+// «esto mejoró río arriba»: comparar contra el fork mismo mediría las ediciones de la empresa.
+function readForks(root) { return readAll(root).forks }
+
 // Cada sección que no se pasa se conserva: `upgrade` no sabe del wiring y `install` no sabe de la
 // instancia, y ninguno de los dos debería borrar lo que el otro anotó.
-function write(root, files, runners) {
+function write(root, files, runners, forks) {
   const current = readAll(root)
   const target = path.join(root, FILE)
   fs.mkdirSync(path.dirname(target), { recursive: true })
@@ -51,6 +58,7 @@ function write(root, files, runners) {
     version: 1,
     files: ordered(files || current.files),
     runners: ordered(runners || current.runners),
+    forks: ordered(forks || current.forks),
   }
   fs.writeFileSync(target, `${JSON.stringify(data, null, 2)}\n`)
 }
@@ -85,4 +93,6 @@ function edited(root, relative, files) {
   })
 }
 
-module.exports = { FILE, digest, digestText, edited, prune, read, readRunners, record, write }
+module.exports = {
+  FILE, digest, digestText, edited, prune, read, readForks, readRunners, record, write,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "type": "commonjs",
   "bin": {