@ingeniomaps/cauce 0.1.0 → 0.2.0

package/engine/cli/ops.js

@@ -10,8 +10,11 @@ const I = require('../integrations/registry')
 const L = require('../agents/learning')
 const A = require('../automation')
 const F = require('../core/files')
+const O = require('../core/ownership')
+const CL = require('../core/changelog')
 const C = require('../config/validate')
 const T = require('../teams/registry')
+const AG = require('../agents/catalog')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
@@ -22,10 +25,11 @@ function fail(message, code = 1) {
 
 function usage() {
   console.log(`Uso:
-  ops init <destino> [--name <nombre>] [--mode embedded|sidecar] [--force]
+  ops init <destino> [--name <nombre>] [--mode embedded|sidecar] [--engine copy|dependency] [--force]
   ops check <planning-dir> [--json]
   ops tree <planning-dir> [--no-color] [--json]
   ops context <planning-dir> [--json]
+  ops upgrade <ops-root> [--check] [--force]
   ops archive <planning-dir> <NNN>
   ops integration list <ops-root>
   ops integration check <ops-root> [provider]
@@ -42,6 +46,7 @@ function usage() {
   ops automation install <ops-root> claude|codex|gemini|antigravity
   ops learn <agent> [--proposal]
   ops evaluate <agent>
+  ops agents list [ops-root] [--json]
   ops team list
   ops team check <team>
   ops team show <team>`)
@@ -75,13 +80,14 @@ function copyTemplate(source, target, replacements, force, skip = []) {
   }
 }
 
-function copyRuntime(source, target, preserve = false, boundary = target) {
+function copyRuntime(source, target, preserve = false, boundary = target, skip = []) {
   F.assertNoSymlinkPath(boundary, target)
   fs.mkdirSync(target, { recursive: true })
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
     const to = path.join(target, entry.name)
-    if (entry.isDirectory()) copyRuntime(from, to, preserve, boundary)
+    if (entry.isDirectory()) copyRuntime(from, to, preserve, boundary, skip)
     else if (preserve && fs.existsSync(to)) console.log(`= conservado ${to}`)
     else {
       F.assertNoSymlinkPath(boundary, to)
@@ -90,6 +96,19 @@ function copyRuntime(source, target, preserve = false, boundary = target) {
   }
 }
 
+// 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)
+}
+
 function init(target) {
   if (!target) fail('Falta <destino>.', 2)
   const mode = option('--mode', 'embedded')
@@ -137,6 +156,8 @@ function init(target) {
     path.join(root, 'automatization', 'runners'),
     preserve,
     root,
+    // El README de runners lo provee el template: le habla al proyecto, no a quien desarrolla Cauce.
+    O.TEMPLATE_OWNED.filter((owned) => owned.startsWith('automatization/runners/')).map((owned) => path.basename(owned)),
   )
   copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'workflows'),
@@ -144,10 +165,25 @@ function init(target) {
     preserve,
     root,
   )
-  const engine = path.join(root, '.ops', 'engine')
-  copyRuntime(path.join(PROJECT_ROOT, 'engine'), engine, preserve, root)
-  fs.chmodSync(path.join(engine, 'cli', 'ops.js'), 0o755)
+  const version = require(path.join(PROJECT_ROOT, 'package.json')).version
+  // Un repo con npm recibe el motor como dependencia versionada; uno de Go, Python o Rust recibe
+  // la copia, porque exigirle un package.json para correr su planning sería imponerle un stack.
+  const manifest = path.join(root, 'package.json')
+  const engineMode = option('--engine', fs.existsSync(manifest) ? 'dependency' : 'copy')
+  if (!['copy', 'dependency'].includes(engineMode)) fail('--engine debe ser copy o dependency.', 2)
+  if (engineMode === 'dependency') declareEngine(manifest, version)
+  else {
+    const engine = path.join(root, '.ops', 'engine')
+    copyRuntime(path.join(PROJECT_ROOT, 'engine'), engine, preserve, root)
+    fs.chmodSync(path.join(engine, 'cli', 'ops.js'), 0o755)
+  }
+  // La instancia recuerda de qué versión salió: sin esto no hay actualización posible.
+  const configFile = path.join(root, 'ops.config.json')
+  const config = JSON.parse(fs.readFileSync(configFile, 'utf8'))
+  config.cauceVersion = version
+  F.atomicWriteJson(configFile, config)
   console.log(`\n✓ ${name}: sistema ops creado en ${root}`)
+  if (engineMode === 'dependency') console.log('  siguiente: npm install (el motor viene de la dependencia)')
   console.log(`  siguiente: node ${path.join(root, 'tools', 'ops.js')} check ${path.join(root, 'planning')}`)
 }
 
@@ -254,6 +290,12 @@ function check(dir) {
   errors.push(...integration.errors)
   warnings.push(...integration.warnings)
 
+  // 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)`)
+  }
+
   if (process.argv.includes('--json')) {
     console.log(JSON.stringify({
       ok: !errors.length,
@@ -414,6 +456,104 @@ function context(dir) {
   for (const action of report.humanActions) console.log(`HUMAN  ${action.task}: ${action.action}`)
 }
 
+// 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 || ''
+  } catch { return '' }
+}
+
+// Sobrescribe lo que trae el paquete y deja intacto lo demás: un guard propio de la empresa,
+// o un adaptador de runner que el toolkit no conoce, sobreviven a la actualización.
+function overlayTree(from, to, root, skip = []) {
+  F.assertNoSymlinkPath(root, to)
+  copyRuntime(from, to, false, root, skip)
+}
+
+// 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) {
+  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)
+  }
+  const dry = process.argv.includes('--check')
+  const force = process.argv.includes('--force')
+  const from = instanceVersion(root)
+  const to = require(path.join(PROJECT_ROOT, 'package.json')).version
+  const system = O.systemPaths(root)
+  const changed = O.localChanges(root, PROJECT_ROOT)
+  const overrides = O.overrides(root)
+
+  if (dry) {
+    if (from === to) return console.log(`= ${to}: la instancia está al día`)
+    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)
+  }
+
+  if (changed.length && !force) {
+    for (const file of changed) console.error(`✗ ${file}`)
+    fail(
+      `\n${changed.length} archivo(s) del runtime fueron editados y se perderían.\n` +
+      'Movelos junto a system/ como regla propia, o repetí con --force para descartarlos.',
+    )
+  }
+
+  for (const relative of [...system, ...O.RUNTIME_PATHS]) {
+    const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
+    if (!fs.existsSync(origin)) continue
+    const target = path.join(root, relative)
+    // Una instancia que toma el motor de npm no debe recuperar la copia: la actualiza el lockfile.
+    if (relative === '.ops/engine' && !fs.existsSync(target)) continue
+    const skip = O.TEMPLATE_OWNED
+      .filter((owned) => owned.startsWith(`${relative}/`))
+      .map((owned) => path.basename(owned))
+    if (fs.statSync(origin).isDirectory()) overlayTree(origin, target, root, skip)
+    else {
+      F.assertNoSymlinkPath(root, target)
+      F.atomicWrite(target, fs.readFileSync(origin, 'utf8'))
+    }
+  }
+
+  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)
+
+  console.log(`✓ Cauce ${from || '(previa)'} → ${to}`)
+  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}`)
+  }
+  console.log('  planning, organization y todo lo propio quedaron intactos')
+}
+
+// Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
+// reimplemente el recorrido del catálogo.
+function agents(action, dir) {
+  if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
+  const root = path.resolve(dir || '.')
+  const roles = AG.list(root)
+  if (process.argv.includes('--json')) {
+    return console.log(JSON.stringify(roles.map((role) => ({
+      slug: role.slug, type: role.type, system: role.system,
+    }))))
+  }
+  for (const role of roles) console.log(`${role.slug}${role.system ? '' : '  (propio)'}`)
+}
+
 function archive(dir, rawNum) {
   const root = path.resolve(dir || '.')
   const num = String(rawNum || '').padStart(3, '0')
@@ -570,6 +710,8 @@ function team(action, slug) {
     for (const error of result.errors) console.error(`✗ ${error}`)
     if (result.errors.length) fail(`${slug}: ${result.errors.length} error(es)`, 1)
     if (action === 'show') {
+      // El manifiesto entero, para que un workflow ejecute las etapas sin que un modelo lo parsee.
+      if (process.argv.includes('--json')) return console.log(JSON.stringify(result.manifest))
       console.log(`${result.manifest.name} (${slug})`)
       console.log(result.manifest.purpose)
       for (const stage of result.manifest.stages) {
@@ -588,6 +730,8 @@ async function main() {
   else if (command === 'check') check(process.argv[3])
   else if (command === 'tree') tree(process.argv[3])
   else if (command === 'context') context(process.argv[3])
+  else if (command === 'upgrade') upgrade(process.argv[3])
+  else if (command === 'agents') agents(process.argv[3], process.argv[4])
   else if (command === 'archive') archive(process.argv[3], process.argv[4])
   else if (command === 'integration') {
     await integration(process.argv[3], process.argv[4], process.argv[5], process.argv[6])

package/engine/config/validate.js

@@ -7,7 +7,10 @@ function validateOpsConfig(config) {
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
     return ['ops.config.json: debe ser un objeto']
   }
-  const allowed = new Set(['$schema', 'project', 'mode', 'planningDir', 'workspaceRoots', 'runner'])
+  // `cauceVersion` la escribe el toolkit, no la persona: registra de qué versión salió la instancia.
+  const allowed = new Set([
+    '$schema', 'cauceVersion', 'project', 'mode', 'planningDir', 'workspaceRoots', 'runner',
+  ])
   for (const key of Object.keys(config)) {
     if (!allowed.has(key)) errors.push(`ops.config.json: propiedad desconocida ${key}`)
   }

package/engine/core/changelog.js

@@ -0,0 +1,50 @@
+'use strict'
+
+// `upgrade` reemplaza `system/` sin pedir confirmación. Mostrar qué cambió entre la versión
+// instalada y la nueva es lo que separa "actualizarse rápido" de "actualizarse a ciegas".
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const HEADING = /^##\s*\[([^\]]+)\]/
+
+// Compara versiones semver sin dependencias. Lo no numérico ordena antes que la release.
+function compare(left, right) {
+  const parse = (value) => String(value).split('-')[0].split('.').map((part) => Number(part) || 0)
+  const [a, b] = [parse(left), parse(right)]
+  for (let index = 0; index < 3; index++) {
+    if ((a[index] || 0) !== (b[index] || 0)) return (a[index] || 0) - (b[index] || 0)
+  }
+  return 0
+}
+
+function entries(text) {
+  const found = []
+  let current = null
+  for (const line of text.split('\n')) {
+    const heading = line.match(HEADING)
+    if (heading) {
+      current = { version: heading[1], lines: [] }
+      found.push(current)
+      continue
+    }
+    if (current) current.lines.push(line)
+  }
+  return found.map((entry) => ({ version: entry.version, body: entry.lines.join('\n').trim() }))
+}
+
+// Entradas estrictamente posteriores a `from` y hasta `to`. Una versión no publicada se incluye
+// siempre: es justamente la que el usuario está por recibir desde el paquete.
+function between(text, from, to) {
+  return entries(text).filter((entry) => {
+    if (!/^\d/.test(entry.version)) return true
+    if (from && compare(entry.version, from) <= 0) return false
+    return !to || compare(entry.version, to) <= 0
+  })
+}
+
+function read(packageRoot) {
+  try { return fs.readFileSync(path.join(packageRoot, 'CHANGELOG.md'), 'utf8') } catch { return '' }
+}
+
+module.exports = { between, compare, entries, read }

package/engine/core/ownership.js

@@ -0,0 +1,168 @@
+'use strict'
+
+// Frontera entre lo que actualiza el toolkit y lo que pertenece al proyecto.
+// Es la fuente única: `check` reporta overrides contra esto y `upgrade` decide qué reemplaza.
+//
+// La regla es una carpeta, no un diff: nada fuera de esta declaración se toca jamás.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// Archivos de los que el toolkit es único autor. Un proyecto que necesite cambiarlos no los
+// edita: agrega una regla propia junto a las de `system/`, que sí sobrevive al upgrade.
+const SYSTEM_FILES = [
+  'planning/PROTOCOL.md',
+  'planning/FLOW.md',
+  'planning/METHODOLOGY.md',
+  'planning/README.md',
+  'planning/adr/000-template.md',
+  'planning/adr/README.md',
+  'planning/business-rules/000-template.md',
+  'planning/business-rules/README.md',
+  'planning/rules/README.md',
+  'planning/roadmap/README.md',
+  'planning/roadmap/epic-000-template.md',
+]
+
+// Colecciones mixtas: el toolkit posee `<dir>/system/`, el proyecto todo lo demás del directorio.
+const SYSTEM_COLLECTIONS = [
+  'planning/adr',
+  'planning/business-rules',
+  'planning/rules',
+  'teams',
+]
+
+// Copias del runtime: el proyecto las recibe para poder ejecutar sin red, pero no las escribe.
+// Se reemplazan enteras. Mientras no tengan su propio `system/`, una edición local se detecta y
+// se reporta antes de pisarla, nunca después.
+const RUNTIME_PATHS = [
+  '.ops/engine',
+  'automatization/hooks',
+  'automatization/runners',
+  'automatization/workflows',
+]
+
+// Rutas que el paquete tiene por duplicado: una versión para el proyecto en `template/` y otra
+// interna del toolkit. Gana la del template, que es la que le habla a quien usa la instancia.
+const TEMPLATE_OWNED = ['automatization/runners/README.md']
+
+// Dentro del paquete, lo que una instancia recibe en su raíz vive bajo `template/`; el catálogo,
+// los equipos y la automatización están en la raíz del paquete, y el motor en `engine/`.
+function sourceOf(relative) {
+  if (relative === '.ops/engine') return 'engine'
+  if (relative.startsWith('planning/')) return path.join('template', relative)
+  return relative
+}
+
+// Dónde puede estar el motor, en orden de preferencia. Lo mismo que resuelven `tools/ops.js`,
+// el wrapper de hooks y el bridge de Antigravity: declararlo una vez evita que un consumidor
+// quede afuera cuando aparece una forma nueva de instalarlo.
+function engineCandidates(root) {
+  return [
+    path.join(root, 'node_modules', '@ingeniomaps', 'cauce', 'engine'),
+    path.join(root, '.ops', 'engine'),
+    path.join(root, 'engine'),
+  ]
+}
+
+function engineAt(root, relative = '') {
+  return engineCandidates(root)
+    .map((dir) => (relative ? path.join(dir, relative) : dir))
+    .find((candidate) => fs.existsSync(candidate)) || ''
+}
+
+// Identidad de una entrada dentro de una colección, para detectar que el proyecto sobrescribe
+// algo del sistema. Las reglas y decisiones se identifican por su ID; el resto, por su nombre.
+const ID_PATTERN = /^(?:BR-)?[A-Z][A-Z0-9]*-\d{3}/
+
+function identity(name) {
+  const base = name.replace(/\.md$/, '')
+  const id = base.match(ID_PATTERN)
+  return id ? id[0] : base
+}
+
+function entries(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.name !== 'README.md' && !entry.name.startsWith('.'))
+      .map((entry) => entry.name)
+  } catch { return [] }
+}
+
+// Entradas del proyecto que reemplazan a una del sistema con la misma identidad.
+function overrides(root) {
+  const found = []
+  for (const collection of SYSTEM_COLLECTIONS) {
+    const dir = path.join(root, collection)
+    const system = new Map()
+    for (const name of entries(path.join(dir, 'system'))) system.set(identity(name), name)
+    if (!system.size) continue
+    for (const name of entries(dir)) {
+      if (name === 'system' || name === '000-template.md') continue
+      const key = identity(name)
+      if (system.has(key)) found.push({ collection, id: key, project: name, system: system.get(key) })
+    }
+  }
+  return found
+}
+
+// Rutas que `upgrade` reemplaza. Todo lo que no aparezca acá pertenece al proyecto.
+function systemPaths(root) {
+  const paths = []
+  for (const file of SYSTEM_FILES) {
+    if (fs.existsSync(path.join(root, file))) paths.push(file)
+  }
+  for (const collection of SYSTEM_COLLECTIONS) {
+    const dir = path.join(root, collection, 'system')
+    if (fs.existsSync(dir)) paths.push(`${collection}/system`)
+  }
+  return paths
+}
+
+// Archivos de un árbol, relativos a él, para comparar instancia contra paquete.
+function treeFiles(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(...treeFiles(path.join(dir, entry.name), relative))
+    else found.push(relative)
+  }
+  return found.sort()
+}
+
+// Archivos del runtime que el proyecto editó: existen en las dos partes y difieren. Un archivo
+// que sólo existe en la instancia es un agregado propio, no una edición, y sobrevive intacto.
+function localChanges(root, packageRoot) {
+  const changed = []
+  for (const target of RUNTIME_PATHS) {
+    const from = path.join(packageRoot, sourceOf(target))
+    const to = path.join(root, target)
+    if (!fs.existsSync(to) || !fs.existsSync(from)) continue
+    for (const file of treeFiles(from)) {
+      if (TEMPLATE_OWNED.includes(`${target}/${file}`)) continue
+      const mine = path.join(to, file)
+      if (!fs.existsSync(mine)) continue
+      if (fs.readFileSync(mine, 'utf8') !== fs.readFileSync(path.join(from, file), 'utf8')) {
+        changed.push(`${target}/${file}`)
+      }
+    }
+  }
+  return changed
+}
+
+module.exports = {
+  RUNTIME_PATHS,
+  engineAt,
+  engineCandidates,
+  TEMPLATE_OWNED,
+  SYSTEM_COLLECTIONS,
+  SYSTEM_FILES,
+  identity,
+  localChanges,
+  overrides,
+  sourceOf,
+  systemPaths,
+  treeFiles,
+}

package/engine/schemas/ops-config.schema.json

@@ -5,6 +5,7 @@
   "required": ["project", "mode", "planningDir", "workspaceRoots", "runner"],
   "properties": {
     "$schema": { "type": "string", "minLength": 1 },
+    "cauceVersion": { "type": "string", "minLength": 1 },
     "project": { "type": "string", "minLength": 1 },
     "mode": { "enum": ["embedded", "sidecar", "toolkit"] },
     "planningDir": { "type": "string", "minLength": 1 },

package/engine/teams/registry.js

@@ -2,23 +2,24 @@
 
 const fs = require('fs')
 const path = require('path')
+const catalog = require('../agents/catalog')
 
 const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
+// El proyecto manda sobre el sistema: un team propio con el mismo slug reemplaza al de `system/`,
+// que se sigue actualizando debajo sin que nadie tenga que forkearlo.
 function teamFile(root, slug) {
   if (!SLUG.test(slug || '')) throw new Error(`team inválido: ${slug || '(vacío)'}`)
-  return path.join(root, 'teams', slug, 'team.json')
+  const own = path.join(root, 'teams', slug, 'team.json')
+  if (fs.existsSync(own)) return own
+  return path.join(root, 'teams', 'system', slug, 'team.json')
 }
 
-function agentMatches(root, slug) {
-  const catalog = path.join(root, 'agents')
-  let types = []
-  try {
-    types = fs.readdirSync(catalog, { withFileTypes: true }).filter((entry) => entry.isDirectory())
-  } catch { return [] }
-  return types
-    .map((entry) => path.join(catalog, entry.name, slug, 'SKILL.md'))
-    .filter((file) => fs.existsSync(file))
+// Devuelve el motivo real: "no existe" y "ambiguo" piden acciones distintas de quien lo lea.
+function agentProblem(root, slug) {
+  try { catalog.resolve(root, slug); return '' } catch (error) {
+    return /ambiguo/.test(error.message) ? `agente ambiguo: ${slug}` : `agente inexistente: ${slug}`
+  }
 }
 
 function read(root, slug) {
@@ -61,25 +62,30 @@ function validate(root, slug) {
   for (const agent of agents) {
     if (!SLUG.test(agent || '')) errors.push(`slug de agente inválido: ${agent || '(vacío)'}`)
     else {
-      const matches = agentMatches(root, agent)
-      if (!matches.length) errors.push(`agente inexistente: ${agent}`)
-      if (matches.length > 1) errors.push(`agente ambiguo: ${agent}`)
+      const problem = agentProblem(root, agent)
+      if (problem) errors.push(problem)
     }
   }
-  const workflow = path.join(root, 'teams', slug, 'WORKFLOW.md')
+  // Junto al team.json que ganó la resolución, no en una ruta fija: el team puede venir de system/.
+  const workflow = path.join(path.dirname(teamFile(root, slug)), 'WORKFLOW.md')
   if (!fs.existsSync(workflow)) errors.push('falta WORKFLOW.md')
   return { errors, stages: (manifest.stages || []).length, agents: agents.size, manifest }
 }
 
-function list(root) {
-  const catalog = path.join(root, 'teams')
+function slugsIn(dir) {
   try {
-    return fs.readdirSync(catalog, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .filter((entry) => fs.existsSync(path.join(catalog, entry.name, 'team.json')))
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name !== 'system')
+      .filter((entry) => fs.existsSync(path.join(dir, entry.name, 'team.json')))
       .map((entry) => entry.name)
-      .sort()
   } catch { return [] }
 }
 
+// Un slug aparece una sola vez aunque exista en los dos niveles: el del proyecto ya ganó.
+function list(root) {
+  const teams = path.join(root, 'teams')
+  const slugs = new Set([...slugsIn(teams), ...slugsIn(path.join(teams, 'system'))])
+  return [...slugs].sort()
+}
+
 module.exports = { list, read, validate }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "type": "commonjs",
   "bin": {
@@ -13,7 +13,8 @@
     "teams/",
     "automatization/",
     ".github/workflows/",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "ops": "node engine/cli/ops.js",

package/template/AGENTS.md

@@ -25,6 +25,39 @@ Por defecto, todo sistema externo se considera real y de solo lectura. Sin aprob
 
 Documentar excepciones concretas aquí. Un entorno de desarrollo o sandbox debe nombrarse explícitamente.
 
+## Cargos disponibles
+
+`agents/` es un catálogo de cargos reutilizables. Cada uno declara en su `SKILL.md` cuándo actuar, qué
+decide, qué no le corresponde y cuál es su entrega mínima; sus métodos viven en `references/`.
+
+Antes de resolver algo que cae claramente en un cargo —una decisión de producto, un diseño de
+arquitectura, una estrategia de pruebas—, adoptá ese contrato en vez de improvisar el criterio. Los
+límites del cargo no son sugerencias: un cargo que no puede decidir solo, no decide solo.
+
+En Claude y Antigravity los cargos aparecen como skills invocables por nombre. En Codex y Gemini no hay
+mecanismo nativo: leé directamente el `SKILL.md` del cargo. Los que trae
+Cauce están en `agents/roles/system/`; los propios del proyecto, en `agents/roles/`, donde un mismo
+slug reemplaza al del sistema.
+
+`teams/` compone varios cargos en etapas con gates de salida y un dueño por dominio de decisión;
+`node tools/ops.js team show <slug>` muestra el recorrido.
+
+## Qué se puede editar y qué no
+
+Todo directorio `system/` pertenece a Cauce y se reemplaza completo al actualizar. **Nunca editar nada
+dentro de `system/`**: el cambio se pierde en la siguiente actualización y, mientras tanto, ese archivo
+deja de recibir mejoras.
+
+Para cambiar algo del sistema hay dos operaciones, las dos junto a `system/`, nunca dentro:
+
+- **Anexar**: un archivo nuevo con nombre o ID propio. Convive con los del sistema.
+- **Reemplazar**: un archivo con el mismo nombre o ID que uno de `system/`. El del proyecto manda y
+  `check` lo reporta como override explícito en vez de fallar.
+
+Aplica a `planning/business-rules/`, `planning/adr/`, `planning/rules/`, `teams/` y `agents/`. El resto de
+`planning/` —roadmap, backlog, WIP, done, inbox y acciones humanas— es del proyecto y no se toca al
+actualizar.
+
 ## Cómo leer el estado
 
 Antes de abrir un archivo de `planning/`, preguntarle al CLI: es determinista, no gasta contexto y no

package/template/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-.PHONY: help check tree context automation-check
+.PHONY: help check tree context upgrade automation-check
 .PHONY: require-agent agent-learn agent-propose agent-evaluate
 .PHONY: install-claude install-codex install-gemini install-antigravity
 .PHONY: doctor-claude doctor-codex doctor-gemini doctor-antigravity
@@ -18,6 +18,9 @@ tree: ## Muestra roadmap, backlog, WIP y Done
 context: ## Muestra el contexto mínimo de la tarea vigente
 	@node tools/ops.js context planning
 
+upgrade: ## Actualiza Cauce sin tocar lo del proyecto
+	@node tools/ops.js upgrade .
+
 automation-check: ## Comprueba hooks, workflows y adaptadores
 	@node tools/ops.js automation check .
 

package/template/planning/rules/README.md

@@ -1,7 +1,13 @@
 # Reglas transversales
 
-- `process.md`: planificación, alcance, review y sincronización de estado.
-- `code-shape.md`: simplicidad y forma del cambio.
-- `commits.md`: historia versionada y entrega.
+`system/` pertenece a Cauce y se reemplaza completo en cada actualización:
+
+- `system/process.md`: planificación, alcance, review y sincronización de estado.
+- `system/code-shape.md`: simplicidad y forma del cambio.
+- `system/commits.md`: historia versionada y entrega.
+
+Las reglas propias del proyecto van en este directorio, junto a `system/`, y nunca se tocan al
+actualizar. Para cambiar una regla del sistema, escribí la tuya con el mismo nombre: la del proyecto
+manda y `check` reporta el override en vez de fallar.
 
 Las convenciones específicas de lenguaje viven junto al servicio que usa ese lenguaje.