@ingeniomaps/cauce 0.3.0 → 0.4.0

package/agents/roles/system/ui-designer/SKILL.md

@@ -11,6 +11,8 @@ Actuar como responsable del lenguaje visual de la interfaz y su aplicación sist
 
 1. Localizar la raíz operativa del proyecto.
 2. Leer `AGENTS.md`, `ops.config.json` y `organization/README.md` si existen.
+   Leer también `organization/roles/ui-designer.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 3. Leer `organization/company.md`, `organization/product.md` y cualquier guía de marca o design system autorizado.
 4. Leer el flujo y criterios entregados por UX Designer, además de evidencia relevante y restricciones confirmadas.
 5. Inspeccionar componentes, tokens y convenciones existentes antes de crear otros. Separar hechos, restricciones y supuestos. No inventar marca, usuarios, métricas ni evidencia observable.

package/agents/roles/system/ui-designer/learning/sources.yaml

@@ -5,6 +5,8 @@ rules:
   reject_unsourced_claims: true
   automatic_apply: false
 
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/ui-designer.md dentro de cada instalación.
 sources:
   - name: W3C Web Accessibility Initiative
     url: https://www.w3.org/WAI/

package/agents/roles/system/user-researcher/SKILL.md

@@ -11,6 +11,8 @@ Actuar como responsable de producir evidencia confiable sobre usuarios. Explicar
 
 1. Localizar la raíz operativa del proyecto.
 2. Leer `AGENTS.md`, `ops.config.json` y `organization/README.md` si existen.
+   Leer también `organization/roles/user-researcher.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 3. Leer `organization/company.md` y `organization/product.md`. Consultar políticas de privacidad, seguridad, accesibilidad y salvaguarda cuando apliquen.
 4. Leer sólo el estado de `planning/` necesario para comprender la decisión que la investigación debe informar.
 5. Clasificar cada entrada como dato original, observación, interpretación, inferencia, supuesto o pregunta.

package/agents/roles/system/user-researcher/learning/sources.yaml

@@ -5,6 +5,8 @@ rules:
   reject_unsourced_claims: true
   automatic_apply: false
 
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/user-researcher.md dentro de cada instalación.
 sources:
   - name: GOV.UK User Research
     url: https://www.gov.uk/service-manual/user-research

package/agents/roles/system/ux-designer/SKILL.md

@@ -11,6 +11,8 @@ Actuar como responsable de la estructura y comportamiento de la experiencia. Red
 
 1. Localizar la raíz operativa del proyecto.
 2. Leer `AGENTS.md`, `ops.config.json` y `organization/README.md` si existen.
+   Leer también `organization/roles/ux-designer.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 3. Leer `organization/company.md`, `organization/product.md` y las reglas de diseño o accesibilidad disponibles.
 4. Consultar evidencia del User Researcher y decisiones aprobadas del Product Manager. Leer el estado de `planning/` necesario.
 5. Separar hechos, evidencia, restricciones, supuestos y decisiones pendientes. No inventar investigación, usuarios, métricas ni evidencia observable.

package/agents/roles/system/ux-designer/learning/sources.yaml

@@ -5,6 +5,8 @@ rules:
   reject_unsourced_claims: true
   automatic_apply: false
 
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/ux-designer.md dentro de cada instalación.
 sources:
   - name: W3C Web Accessibility Initiative
     url: https://www.w3.org/WAI/

package/engine/agents/catalog.js

@@ -1,15 +1,18 @@
 'use strict'
 
 // Resolución única del catálogo de cargos. La usan el ciclo de aprendizaje, la validación de
-// equipos y la instalación en runners: tres lugares que antes resolvían por su cuenta.
+// equipos y la instalación en runners.
 //
-// Cada tipo separa lo del toolkit de lo del proyecto igual que el resto de las colecciones:
+// El catálogo se reparte en dos lugares según de quién es cada cosa:
 //
-//   agents/<tipo>/system/<slug>/SKILL.md   viene con Cauce y se reemplaza al actualizar
-//   agents/<tipo>/<slug>/SKILL.md          es del proyecto y manda sobre el anterior
+//   <paquete>/agents/<tipo>/system/<slug>/   viene con Cauce, se actualiza con la dependencia
+//   <proyecto>/agents/<tipo>/<slug>/         es de la empresa y manda sobre el anterior
 //
-// Un slug repetido entre tipos distintos sigue siendo ambiguo: ahí no hay ninguna regla que
-// diga cuál gana, y elegir en silencio sería peor que fallar.
+// Los cargos del sistema no se copian al proyecto: evolucionan como profesión y esa evolución es
+// la misma para todos. Lo que sí es de cada empresa —su contexto— vive en `organization/roles/`.
+//
+// Un slug repetido entre tipos distintos sigue siendo ambiguo: ahí no hay ninguna regla que diga
+// cuál gana, y elegir en silencio sería peor que fallar.
 
 const fs = require('node:fs')
 const path = require('node:path')
@@ -24,44 +27,66 @@ function directories(dir) {
   } catch { return [] }
 }
 
+// Dónde está el catálogo que trae Cauce. Se reconoce por tener `roles/system/`, que es el espacio
+// del sistema y no algo que un proyecto deba crear.
+function systemCatalog(root) {
+  return require('../core/ownership').packageDir(root, 'agents')
+}
+
+function projectCatalog(root) {
+  return path.join(root, 'agents')
+}
+
 function types(root) {
-  return directories(path.join(root, 'agents'))
+  const own = directories(projectCatalog(root))
+  const system = directories(systemCatalog(root) || path.join(root, '\0'))
+  return [...new Set([...own, ...system])]
 }
 
-// Todos los cargos visibles: los del proyecto ocultan a los del sistema con el mismo slug.
+// Todos los cargos visibles: los de la empresa ocultan a los del sistema con el mismo slug.
 function list(root) {
-  const catalog = path.join(root, 'agents')
+  const system = systemCatalog(root)
   const found = new Map()
   for (const type of types(root)) {
-    const base = path.join(catalog, type)
-    // El sistema primero para que el proyecto lo sobrescriba al pasar por encima.
-    for (const [source, system] of [[path.join(base, 'system'), true], [base, false]]) {
+    // El sistema primero, para que el proyecto lo sobrescriba al pasar por encima.
+    const sources = [
+      system ? [path.join(system, type, 'system'), true] : null,
+      [path.join(projectCatalog(root), type), false],
+    ].filter(Boolean)
+    for (const [source, fromSystem] of sources) {
       for (const slug of directories(source)) {
         if (slug === 'system' || !SLUG.test(slug)) continue
         const dir = path.join(source, slug)
         if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue
-        found.set(slug, { slug, type, dir, system })
+        found.set(slug, { slug, type, dir, system: fromSystem })
       }
     }
   }
   return [...found.values()].sort((left, right) => left.slug.localeCompare(right.slug))
 }
 
-function resolve(root, slug) {
+function find(root, slug) {
   if (!SLUG.test(slug || '')) throw new Error(`agente inválido: ${slug || '(vacío)'}`)
+  const system = systemCatalog(root)
   const matches = []
   for (const type of types(root)) {
-    const own = path.join(root, 'agents', type, slug)
-    const system = path.join(root, 'agents', type, 'system', slug)
+    const own = path.join(projectCatalog(root), type, slug)
+    const shipped = system ? path.join(system, type, 'system', slug) : ''
     // Dentro de un tipo la precedencia está definida; entre tipos no, y por eso se acumulan.
-    if (fs.existsSync(path.join(own, 'SKILL.md'))) matches.push(own)
-    else if (fs.existsSync(path.join(system, 'SKILL.md'))) matches.push(system)
+    if (fs.existsSync(path.join(own, 'SKILL.md'))) matches.push({ dir: own, system: false })
+    else if (shipped && fs.existsSync(path.join(shipped, 'SKILL.md'))) {
+      matches.push({ dir: shipped, system: true })
+    }
   }
   if (!matches.length) throw new Error(`no existe agents/<tipo>/${slug}/SKILL.md`)
   if (matches.length > 1) {
-    throw new Error(`agente ambiguo ${slug}: ${matches.map((dir) => path.relative(root, dir)).join(', ')}`)
+    throw new Error(`agente ambiguo ${slug}: ${matches.map((entry) => entry.dir).join(', ')}`)
   }
   return matches[0]
 }
 
-module.exports = { list, resolve, types }
+function resolve(root, slug) {
+  return find(root, slug).dir
+}
+
+module.exports = { find, list, projectCatalog, resolve, systemCatalog, types }

package/engine/agents/learning.js

@@ -19,11 +19,28 @@ function agentRoot(root, agent) {
   return catalog.resolve(root, agent)
 }
 
+// Un cargo del sistema vive dentro del paquete: escribir ahí perdería el informe en el próximo
+// `npm ci`, y además duplicaría en cada empresa una investigación sobre la profesión que se hace
+// mejor una sola vez. Lo que sí es de esta empresa es su contexto, y ese tiene otro lugar.
+function assertWritable(root, agent) {
+  const found = catalog.find(root, agent)
+  // Lo que decide no es si el cargo es del sistema, sino si vive dentro de este repositorio. En el
+  // toolkit los cargos del sistema son propios y se aprenden acá; en una instancia vienen del
+  // paquete, y escribir ahí se pierde en el próximo `npm ci` o en el próximo upgrade.
+  const own = path.resolve(catalog.projectCatalog(root))
+  if (path.resolve(found.dir).startsWith(`${own}${path.sep}`)) return found.dir
+  throw new Error(
+    `${agent} es un cargo que trae Cauce y su aprendizaje se hace en el toolkit, no acá.\n` +
+    `  Lo que este cargo debe saber de esta empresa va en organization/roles/${agent}.md.\n` +
+    `  Para tener una versión propia del cargo, escribila en agents/roles/${agent}/.`,
+  )
+}
+
 function isoDate(now = new Date()) { return now.toISOString().slice(0, 10) }
 function month(now = new Date()) { return now.toISOString().slice(0, 7) }
 
 function prepareReport(root, agent, now = new Date()) {
-  const reports = path.join(agentRoot(root, agent), 'learning', 'reports')
+  const reports = path.join(assertWritable(root, agent), 'learning', 'reports')
   const file = path.join(reports, `${isoDate(now)}.md`)
   fs.mkdirSync(reports, { recursive: true })
   if (fs.existsSync(file)) return { file, created: false }
@@ -51,7 +68,7 @@ status: draft
 }
 
 function prepareProposal(root, agent, now = new Date()) {
-  const target = agentRoot(root, agent)
+  const target = assertWritable(root, agent)
   const proposalDir = path.join(target, 'learning', 'proposals')
   const file = path.join(proposalDir, `${month(now)}.md`)
   fs.mkdirSync(proposalDir, { recursive: true })

package/engine/cli/ops.js

@@ -12,6 +12,7 @@ const A = require('../automation')
 const F = require('../core/files')
 const O = require('../core/ownership')
 const CL = require('../core/changelog')
+const M = require('../core/manifest')
 const C = require('../config/validate')
 const T = require('../teams/registry')
 const AG = require('../agents/catalog')
@@ -125,25 +126,13 @@ function init(target) {
     '{{PLANNING_DIR}}': 'planning',
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
   }, process.argv.includes('--force'))
-  copyTemplate(path.join(PROJECT_ROOT, 'agents'), path.join(root, 'agents'), {
-    '{{PROJECT_NAME}}': name,
-    '{{MODE}}': mode,
-    '{{PLANNING_DIR}}': 'planning',
-    '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-  }, process.argv.includes('--force'))
-  copyTemplate(path.join(PROJECT_ROOT, 'teams'), path.join(root, 'teams'), {
-    '{{PROJECT_NAME}}': name,
-    '{{MODE}}': mode,
-    '{{PLANNING_DIR}}': 'planning',
-    '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-  }, process.argv.includes('--force'))
   // `ci.yml` valida el toolkit con `npm run ci`; una instancia no tiene ese script ni sus pruebas.
   copyTemplate(path.join(PROJECT_ROOT, '.github', 'workflows'), path.join(root, '.github', 'workflows'), {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
     '{{PLANNING_DIR}}': 'planning',
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-  }, process.argv.includes('--force'), ['ci.yml'])
+  }, process.argv.includes('--force'), ['ci.yml', 'agent-learning.yml'])
   const preserve = process.argv.includes('--force')
   copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'hooks'),
@@ -176,11 +165,24 @@ function init(target) {
     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)
+    // Sin npm no hay de dónde leer el catálogo en tiempo de ejecución: viaja junto al motor.
+    copyRuntime(path.join(PROJECT_ROOT, 'agents'), path.join(root, '.ops', 'agents'), preserve, root)
+    copyRuntime(path.join(PROJECT_ROOT, 'teams'), path.join(root, '.ops', 'teams'), preserve, root)
+  }
+  let entregado = {}
+  for (const relative of O.trackedPaths()) {
+    const dir = path.join(root, relative)
+    if (fs.existsSync(dir)) entregado = { ...entregado, ...M.record(root, relative, O.treeFiles(dir)) }
   }
+  M.write(root, entregado)
   // 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
+  // El esquema vive donde quedó el motor; la plantilla no puede saberlo de antemano.
+  config.$schema = engineMode === 'dependency'
+    ? 'node_modules/@ingeniomaps/cauce/engine/schemas/ops-config.schema.json'
+    : '.ops/engine/schemas/ops-config.schema.json'
   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)')
@@ -492,7 +494,7 @@ function upgrade(dir) {
   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 changed = O.localChanges(root)
   const overrides = O.overrides(root)
 
   if (dry) {
@@ -503,14 +505,37 @@ function upgrade(dir) {
     process.exit(1)
   }
 
+  // Antes de retirar nada, comprobar que no se lleve puesto aprendizaje acumulado.
+  const rescatar = O.retiredWithLearning(root)
+  if (rescatar.length && !force) {
+    for (const file of rescatar) console.error(`✗ ${file}`)
+    fail(
+      `\n${rescatar.length} archivo(s) de aprendizaje quedaron en una ruta que Cauce ya no mantiene.\n\n` +
+      'Movelos a un cargo propio en agents/roles/<slug>/learning/ y repetí, o descartalos con --force.',
+    )
+  }
+
   if (changed.length && !force) {
     for (const file of changed) console.error(`✗ ${file}`)
+    const reglas = changed.filter((file) => file.includes('/system/'))
+    const runtime = changed.filter((file) => !file.includes('/system/'))
+    const guia = []
+    if (reglas.length) {
+      guia.push(
+        'Las reglas 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) {
+      guia.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.',
+      )
+    }
     fail(
-      `\n${changed.length} archivo(s) del runtime fueron editados y se perderían.\n\n` +
-      '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.\n' +
-      'Si el cambio ya no te sirve, repetí con --force para descartarlo.',
+      `\n${changed.length} archivo(s) que mantiene Cauce fueron editados y se perderían.\n\n` +
+      `${guia.join('\n\n')}\n\nSi el cambio ya no te sirve, repetí con --force para descartarlo.`,
     )
   }
 
@@ -518,8 +543,9 @@ function upgrade(dir) {
     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
+    // `.ops/` es el paquete vendorizado de una instancia sin npm. Si no existe, esta instancia lo
+    // toma de la dependencia y crearlo sería duplicar lo que el lockfile ya versiona.
+    if (relative.startsWith('.ops/') && !fs.existsSync(target)) continue
     const skip = O.TEMPLATE_OWNED
       .filter((owned) => owned.startsWith(`${relative}/`))
       .map((owned) => path.basename(owned))
@@ -530,6 +556,25 @@ function upgrade(dir) {
     }
   }
 
+  // Retirar lo que el toolkit ya no distribuye, después de haber actualizado lo que sí.
+  const retirado = []
+  for (const relative of O.RETIRED) {
+    const target = path.join(root, relative)
+    if (!fs.existsSync(target)) continue
+    F.assertNoSymlinkPath(root, target)
+    fs.rmSync(target, { recursive: true, force: true })
+    retirado.push(relative)
+  }
+
+  // Dejar registrado lo que se entregó, para poder distinguir después una edición local de una
+  // mejora del toolkit.
+  let registro = M.read(root)
+  for (const relative of O.trackedPaths()) {
+    const dir = path.join(root, relative)
+    if (fs.existsSync(dir)) registro = { ...registro, ...M.record(root, relative, O.treeFiles(dir)) }
+  }
+  M.write(root, registro)
+
   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)
@@ -538,6 +583,7 @@ function upgrade(dir) {
   // 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 retirado) console.log(`− retirado ${relative}: Cauce ya no lo distribuye`)
   printChangelog(from, to)
   console.log(`  ${system.length} ruta(s) del sistema y ${O.RUNTIME_PATHS.length} del runtime actualizadas`)
   for (const override of overrides) {

package/engine/core/manifest.js

@@ -0,0 +1,54 @@
+'use strict'
+
+// Qué entregó Cauce y con qué contenido. Sin este registro no se puede distinguir un archivo que
+// la empresa editó de uno que cambió río arriba: los dos se ven igual comparando la instancia
+// contra el paquete, y `upgrade` terminaría negándose ante cualquier mejora del toolkit.
+//
+// Se guarda junto a la configuración porque es estado de la instalación, no del producto, y se
+// commitea: todo el equipo tiene que ver lo mismo.
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const FILE = path.join('.cauce', 'manifest.json')
+
+function digest(file) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex').slice(0, 16)
+  } catch { return '' }
+}
+
+function read(root) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(root, FILE), 'utf8'))
+    return data && typeof data.files === 'object' ? data.files : {}
+  } catch { return {} }
+}
+
+function write(root, files) {
+  const target = path.join(root, FILE)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  const ordered = Object.fromEntries(Object.entries(files).sort(([left], [right]) => left.localeCompare(right)))
+  fs.writeFileSync(target, `${JSON.stringify({ version: 1, files: ordered }, null, 2)}\n`)
+}
+
+// Registra lo entregado en una ruta, relativo a la raíz de la instancia.
+function record(root, relative, files) {
+  const current = read(root)
+  for (const file of files) current[`${relative}/${file}`] = digest(path.join(root, relative, file))
+  return current
+}
+
+// Archivos que la empresa modificó después de recibirlos. Un archivo sin registro previo no
+// cuenta: llegó con una versión anterior a este mecanismo, o lo agregó el proyecto.
+function edited(root, relative, files) {
+  const recorded = read(root)
+  return files.filter((file) => {
+    const key = `${relative}/${file}`
+    if (!recorded[key]) return false
+    return recorded[key] !== digest(path.join(root, relative, file))
+  })
+}
+
+module.exports = { FILE, digest, edited, read, record, write }

package/engine/core/ownership.js

@@ -22,6 +22,7 @@ const SYSTEM_FILES = [
   'planning/rules/README.md',
   'planning/roadmap/README.md',
   'planning/roadmap/epic-000-template.md',
+  'organization/roles/README.md',
 ]
 
 // Colecciones mixtas: el toolkit posee `<dir>/system/`, el proyecto todo lo demás del directorio.
@@ -29,7 +30,6 @@ 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.
@@ -37,6 +37,8 @@ const SYSTEM_COLLECTIONS = [
 // se reporta antes de pisarla, nunca después.
 const RUNTIME_PATHS = [
   '.ops/engine',
+  '.ops/agents',
+  '.ops/teams',
   'automatization/hooks',
   'automatization/runners',
   'automatization/workflows',
@@ -48,9 +50,15 @@ 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/`.
+const TEMPLATE_PREFIXES = ['planning/', 'organization/', 'integrations/']
+
 function sourceOf(relative) {
   if (relative === '.ops/engine') return 'engine'
-  if (relative.startsWith('planning/')) return path.join('template', relative)
+  if (relative === '.ops/agents') return 'agents'
+  if (relative === '.ops/teams') return 'teams'
+  if (TEMPLATE_PREFIXES.some((prefix) => relative.startsWith(prefix))) {
+    return path.join('template', relative)
+  }
   return relative
 }
 
@@ -71,6 +79,19 @@ function engineAt(root, relative = '') {
     .find((candidate) => fs.existsSync(candidate)) || ''
 }
 
+// Definiciones que consume el motor —cargos y equipos— y que por eso viajan con el paquete en vez
+// de copiarse. Se reconocen por contener `system/`, que es el espacio del toolkit y no algo que un
+// proyecto deba crear. Una sola implementación para las dos, o divergen.
+function packageDir(root, name) {
+  const candidates = [
+    path.join(root, 'node_modules', '@ingeniomaps', 'cauce', name),
+    path.join(root, '.ops', name),
+    path.join(root, name),
+  ]
+  return candidates.find((dir) => fs.existsSync(path.join(dir, 'system'))
+    || fs.existsSync(path.join(dir, 'roles', 'system'))) || ''
+}
+
 // 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}/
@@ -106,12 +127,35 @@ function overrides(root) {
   return found
 }
 
+// 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.
+const RETIRED = [
+  'agents/roles/system',
+  'teams/system',
+  '.github/workflows/agent-learning.yml',
+]
+
+// Aprendizaje que quedó dentro de una ruta retirada. Es lo único ahí que no se puede reponer, así
+// que se detecta antes de borrar nada: perderlo en silencio sería peor que dejar el directorio.
+function retiredWithLearning(root) {
+  const found = []
+  for (const relative of RETIRED) {
+    const dir = path.join(root, relative)
+    if (!fs.existsSync(dir)) continue
+    for (const file of treeFiles(dir)) {
+      if (!/(^|\/)learning\/(reports|proposals)\//.test(file)) continue
+      if (path.basename(file).startsWith('_')) continue
+      found.push(`${relative}/${file}`)
+    }
+  }
+  return found
+}
+
 // Rutas que `upgrade` reemplaza. Todo lo que no aparezca acá pertenece al proyecto.
+// Se listan aunque todavía no existan en la instancia: así un archivo nuevo del sistema llega en
+// vez de esperar a que alguien lo cree a mano.
 function systemPaths(root) {
-  const paths = []
-  for (const file of SYSTEM_FILES) {
-    if (fs.existsSync(path.join(root, file))) paths.push(file)
-  }
+  const paths = [...SYSTEM_FILES]
   for (const collection of SYSTEM_COLLECTIONS) {
     const dir = path.join(root, collection, 'system')
     if (fs.existsSync(dir)) paths.push(`${collection}/system`)
@@ -132,28 +176,31 @@ function treeFiles(dir, prefix = '') {
   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) {
+// Rutas que Cauce mantiene y que por eso conviene registrar y vigilar.
+function trackedPaths() {
+  return [...RUNTIME_PATHS, ...SYSTEM_COLLECTIONS.map((collection) => `${collection}/system`)]
+}
+
+// Archivos que la empresa editó después de recibirlos. Se compara contra lo que Cauce entregó,
+// no contra el paquete: si se comparara contra el paquete, cualquier mejora del toolkit se vería
+// idéntica a una edición local y bloquearía la actualización.
+function localChanges(root) {
+  const manifest = require('./manifest')
   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}`)
-      }
-    }
+  for (const target of trackedPaths()) {
+    const dir = path.join(root, target)
+    if (!fs.existsSync(dir)) continue
+    for (const file of manifest.edited(root, target, treeFiles(dir))) changed.push(`${target}/${file}`)
   }
   return changed
 }
 
 module.exports = {
+  RETIRED,
+  trackedPaths,
+  packageDir,
   RUNTIME_PATHS,
+  retiredWithLearning,
   engineAt,
   engineCandidates,
   TEMPLATE_OWNED,

package/engine/teams/registry.js

@@ -12,11 +12,16 @@ const OUTCOMES = ['epic', 'report']
 
 // 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 systemTeams(root) {
+  return require('../core/ownership').packageDir(root, 'teams')
+}
+
 function teamFile(root, slug) {
   if (!SLUG.test(slug || '')) throw new Error(`team inválido: ${slug || '(vacío)'}`)
   const own = path.join(root, 'teams', slug, 'team.json')
   if (fs.existsSync(own)) return own
-  return path.join(root, 'teams', 'system', slug, 'team.json')
+  const system = systemTeams(root)
+  return system ? path.join(system, 'system', slug, 'team.json') : own
 }
 
 // Devuelve el motivo real: "no existe" y "ambiguo" piden acciones distintas de quien lo lea.
@@ -93,9 +98,13 @@ function slugsIn(dir) {
 }
 
 // Un slug aparece una sola vez aunque exista en los dos niveles: el del proyecto ya ganó.
+// Los propios de la empresa y los que trae Cauce, sin duplicar un slug que ya ganó el proyecto.
 function list(root) {
-  const teams = path.join(root, 'teams')
-  const slugs = new Set([...slugsIn(teams), ...slugsIn(path.join(teams, 'system'))])
+  const system = systemTeams(root)
+  const slugs = new Set([
+    ...slugsIn(path.join(root, 'teams')),
+    ...(system ? slugsIn(path.join(system, 'system')) : []),
+  ])
   return [...slugs].sort()
 }
 

package/package.json

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

package/template/organization/roles/README.md

@@ -0,0 +1,37 @@
+# Contexto por cargo
+
+Un cargo del catálogo sabe de su profesión, no de esta empresa. Acá va lo que necesita saber para
+trabajar en **este** contexto: `organization/roles/<slug>.md`.
+
+```markdown
+# QA Engineer en Aparatejo
+
+No hay ambiente de staging: la verificación corre contra el entorno local y contra producción con
+datos de prueba. No hay equipo de soporte, así que un defecto que llegue a producción lo paga el
+tiempo de las cuatro personas del equipo.
+
+Cada imagen generada cuesta plata real: una prueba que dispare generación tiene que declarar cuántas.
+```
+
+## Qué va acá y qué no
+
+**Acá**: restricciones reales de esta empresa, herramientas que usa, quién decide qué, límites de
+presupuesto, deudas conocidas, lo que ya se intentó y no funcionó.
+
+**Acá no**: cómo se hace la profesión. Que exista una técnica nueva de testing o que cambie una norma
+le pasa a todas las empresas por igual: eso vive en el catálogo y llega actualizando Cauce.
+
+## Por qué está separado
+
+Los cargos que trae Cauce viven en el paquete y se actualizan con él. Si el contexto de tu empresa
+estuviera escrito dentro de un cargo del catálogo, cada actualización te obligaría a elegir entre
+perder tu contexto o congelar el cargo.
+
+Separados, las dos cosas mejoran sin pisarse: la profesión la mantiene el toolkit, el contexto lo
+mantenés vos.
+
+## Si necesitás cambiar el cargo, no sólo darle contexto
+
+Escribí tu propia versión en `agents/roles/<slug>/`, con el mismo slug: reemplaza a la del catálogo.
+Tené en cuenta que a partir de ahí ese cargo deja de recibir mejoras, así que conviene sólo cuando el
+contrato en sí no te sirve —no cuando lo que falta es contexto—.