@ingeniomaps/cauce 0.52.0 → 0.53.1

package/automatization/workflows/agent-eval.js

@@ -5,7 +5,7 @@
 // misma razón por la que nadie corrige su propio examen.
 //
 // Dónde trabaja el cargo lo decide el modo: en el toolkit, un banco desechable por caso; en una
-// empresa, su propia instancia. El porqué del banco está en `evaluationBench` (engine/cli/ops.js).
+// empresa, su propia instancia. El porqué del banco está en `evaluationBench` (engine/cli/catalog.js).
 // El veredicto, en cambio, se escribe siempre junto al cargo: el banco se borra, el contrato queda.
 export const meta = {
   name: 'agent-eval',
@@ -105,10 +105,10 @@ if (ONLY.length) {
   const pick = pickCases(context.items, ONLY)
   if (pick.missing.length) {
     return stop('caso-inexistente',
-      `${AGENT} no tiene ${pick.missing.join(', ')}. Tiene: ${pick.existen.join(', ')}`)
+      `${AGENT} no tiene ${pick.missing.join(', ')}. Tiene: ${pick.present.join(', ')}`)
   }
   context.items = pick.items
-  log(`Sólo ${ONLY.join(', ')}: el registro va a cubrir ${ONLY.length} de ${pick.existen.length}`)
+  log(`Sólo ${ONLY.join(', ')}: el registro va a cubrir ${ONLY.length} de ${pick.present.length}`)
 }
 // Un banco por caso, preparados por un solo agente: son comandos deterministas, y después la ruta de
 // cada caso se arma sola.

package/automatization/workflows/agent-promote.js

@@ -29,7 +29,7 @@ export const meta = {
 const AGENT = String((typeof args === 'string' ? args : (args || {}).agent) || '').trim()
 const PERIOD = String((args || {}).period || '').trim()
 
-const FIRMA = {
+const SIGNATURE = {
   type: 'object', additionalProperties: false, required: ['dir', 'proposal', 'approved'],
   properties: {
     dir: { type: 'string' },
@@ -42,7 +42,7 @@ const FIRMA = {
   },
 }
 
-const APLICADO = {
+const APPLIED = {
   type: 'object', additionalProperties: false, required: ['applied', 'files'],
   properties: {
     applied: { type: 'boolean' },
@@ -74,7 +74,7 @@ const signature = await agent(
   `- state: the literal state line.\n` +
   `- status: the literal value of the frontmatter "status:" field.\n` +
   `- hasChange: true only if "Cambio propuesto" carries a concrete change; "por definir" means false.`,
-  { schema: FIRMA, label: 'signature' },
+  { schema: SIGNATURE, label: 'signature' },
 )
 if (!signature) return stop('sin-propuesta', `no se pudo leer una propuesta de ${AGENT}`)
 if (!signature.hasChange) {
@@ -119,7 +119,7 @@ const applied = await agent(
   `aplicó de lo que firmó.\n\n` +
   `No toques otros cargos. No hagas commit ni push. Devolvé qué archivos modificaste, el caso nuevo si ` +
   `lo creaste, y las desviaciones —o cadena vacía si no hubo—.`,
-  { schema: APLICADO, label: `aplica:${AGENT}` },
+  { schema: APPLIED, label: `aplica:${AGENT}` },
 )
 if (!applied || !applied.applied) {
   return stop('no-aplicada', 'el cambio no se pudo aplicar; la propuesta queda como estaba')

package/automatization/workflows/autobuild.js

@@ -86,6 +86,7 @@ const PLAN = {
 // Un veredicto sin manifiesto no se puede contrastar: `consulted` enumera lo que quien revisó abrió de
 // verdad, y es lo único que separa al que miró del que aprobó de memoria. No prueba que lo haya leído bien
 // —para eso habría que releerlo—, y esa asimetría es la que lo deja barato (R14).
+//
 // Tres estados porque hay tres cosas distintas que decir, y con un booleano dos se pisan: «no puedo
 // aprobar esto» y «apruebo con algo que hay que corregir antes de entregar» caían las dos en el mismo
 // `false`, así que la primera gastaba igual una vuelta de corrección sobre algo que la corrección no
@@ -147,11 +148,9 @@ const BUILD = {
       properties: { test: { type: 'string' }, failure: { type: 'string' } },
     } },
     blockers: { type: 'array', items: { type: 'string' } },
-    // Estricto en el cómo, flexible en el qué: lo que aparece y el plan no previó tiene dos destinos y
-    // ninguno es el silencio. Un caso que esta tarea puede fijar entra con la prueba que lo fija —por eso
-    // su `test` tiene que estar en `redFirst`—; una decisión que no le toca queda registrada con quién
-    // puede tomarla. Implementarlo sin prueba lo vuelve invisible y descartarlo lo pierde: en los dos
-    // casos el próximo que lo encuentre empieza de cero.
+    // Estricto en el cómo, flexible en el qué: un `kind` por cada uno de los dos destinos que R6 le da a
+    // lo que aparece y el plan no previó. Lo que agrega este recorrido es el enganche — el caso que esta
+    // tarea puede fijar entra con la prueba que lo fija, y por eso su `test` tiene que estar en `redFirst`.
     discovered: { type: 'array', items: { type: 'object', additionalProperties: false,
       required: ['kind', 'detail'],
       properties: {
@@ -228,23 +227,23 @@ const BASE = `Nunca inventes credenciales ni decisiones; registrá los bloqueos
 // Acompaña a todo prompt con schema DECISION: el schema obliga a llenar `consulted`, y esto obliga a
 // llenarlo con lo que se abrió en vez de con lo que se pensaba mirar.
 const MANIFEST = ' Enumerá en consulted cada archivo, diff o comando que hayas abierto de verdad, con su ruta.'
-// Acompaña a todo prompt con schema DECISION. El criterio va escrito porque tres estados sin criterio son
-// tres nombres, y el del medio —el que evita gastar una corrección en lo que no se corrige— es el que se
-// pierde primero.
+// Acompaña a todo prompt con schema DECISION. Sin el criterio escrito los tres estados son tres nombres
+// y el del medio se pierde primero; por qué son tres está donde se declaran.
 const VERDICT = ' Cerrá con verdict=aprobado si no queda nada por corregir antes de entregar; ' +
   'verdict=con-condiciones si lo que falta se corrige dentro de este mismo cambio; y verdict=bloqueado ' +
   'si algo no se resuelve acá —el diseño no lo cubre, falta una decisión ajena, o la corrección excede el ' +
   'alcance—. Marcá blocking=true sólo en el hallazgo que impide entregar: el resto queda registrado y no ' +
   'manda a tocar código.'
+// Lo que hay que corregir antes de entregar. El resto de los hallazgos no desaparece: se registra.
+const blockers = (verdict) => verdict.concerns.filter((one) => one.blocking).map((one) => one.detail)
 // Atajo para reconocer un gate que corrió pruebas sin preguntarle a nadie. No alcanza solo y no
 // pretende hacerlo: `mvn verify`, `gradle build`, `tox`, `bin/rails t` y cualquier `make` con nombre
 // propio corren pruebas y no se parecen a esto, así que el que corrió el comando además lo declara en
 // `ranTests` y vale cualquiera de los dos. Una lista de nombres siempre le va a faltar el siguiente;
 // lo que no puede es frenar una corrida legítima por no conocerlo.
+//
 // El borde izquierdo va explícito en vez de `\b` porque `\b(?:` se lee igual que una llamada a `b()`
 // y la comprobación de identificadores del paquete de pruebas la marca como función inexistente.
-// Lo que hay que corregir antes de entregar. El resto de los hallazgos no desaparece: se registra.
-const blockers = (verdict) => verdict.concerns.filter((one) => one.blocking).map((one) => one.detail)
 const RUNS_TESTS = /(?:^|[\s/:=-])(?:tests?|specs?|pytest|jest|vitest|mocha|rspec|phpunit|ci|check)\b/i
 {{INCLUDE:shared/workflow-finish.js}}
 
@@ -512,8 +511,8 @@ while (rounds++ < MAX_TASKS) {
   // Lo que queda abierto no lo cierra quien lo encuentra, pero tampoco frena lo que sí se pudo entregar.
   // Tres corridas reales terminaron acá y las tres traían `completed: true`: el hueco nunca fue «no puedo»
   // sino «hay un borde que alguien tiene que decidir», y una aceptación escrita en prosa siempre tiene uno.
-  // Frenar por eso frenaba siempre, y un freno que salta siempre se termina apagando. Lo que de verdad
-  // bloquea ya tiene camino —`completed: false` con su blocker—; esto se registra y sigue.
+  // Frenar por eso frenaba siempre, que es el freno que R6 desaconseja. Lo que de verdad bloquea ya
+  // tiene camino —`completed: false` con su blocker—; esto se registra y sigue.
   const openDecisions = build.discovered.filter((entry) => entry.kind === 'open')
   if (openDecisions.length) {
     await write(`Registrá en ${HUMAN} una fila por cada decisión que ${task.id} dejó abierta, con qué la ` +
@@ -522,6 +521,7 @@ while (rounds++ < MAX_TASKS) {
   }
   // Y un caso que sí se fijó acá entra con su prueba o no entró: sin ella el comportamiento nuevo queda
   // sin nada que lo sostenga, y nadie sabe después que debía existir.
+  //
   // Los dos campos salen de la misma respuesta pero se escriben por separado, así que pedirles la misma
   // cadena exacta frena una tarea correcta por haber nombrado el test de dos formas —`TestAlta` acá y
   // `users_test.go::TestAlta` allá—. Alcanza con que uno nombre al otro; lo que sigue frenando, que es de

package/automatization/workflows/flow-eval.js

@@ -39,10 +39,9 @@ const CASES = {
       },
     } },
     forbidden: { type: 'array', items: { type: 'string' } },
-    // Qué CLI existe acá. Una empresa tiene el shim `tools/ops.js`; el repo del toolkit no lo tiene y su
-    // motor está en `engine/cli/ops.js`. `agent-eval` lo aprendió esta mañana y esto quedó con la ruta
-    // puesta a mano: el agente de bancos reportó los cuatro casos como fallidos y el freno de banco
-    // viejo detuvo cuatro corridas cuyos bancos estaban recién borrados.
+    // Qué CLI existe acá, por lo mismo que en `agent-eval` y con el mismo síntoma: sin la ruta puesta,
+    // el agente de bancos reportó los cuatro casos como fallidos y el freno de banco viejo detuvo cuatro
+    // corridas cuyos bancos estaban recién borrados.
     cli: { type: 'string' },
     mode: { type: 'string' },
   },
@@ -92,10 +91,10 @@ if (ONLY.length) {
   const pick = pickCases(context.items, ONLY)
   if (pick.missing.length) {
     return stop('caso-inexistente',
-      `${FLOW} no tiene ${pick.missing.join(', ')}. Tiene: ${pick.existen.join(', ')}`)
+      `${FLOW} no tiene ${pick.missing.join(', ')}. Tiene: ${pick.present.join(', ')}`)
   }
   context.items = pick.items
-  log(`Sólo ${ONLY.join(', ')}: el registro va a cubrir ${ONLY.length} de ${pick.existen.length}`)
+  log(`Sólo ${ONLY.join(', ')}: el registro va a cubrir ${ONLY.length} de ${pick.present.length}`)
 }
 
 // El recorrido escribe: épica candidata, INBOX, acciones humanas. Sin un `planning/` propio no puede
@@ -117,9 +116,13 @@ const benches = await agent(
 )
 if (!benches || !benches.path) return stop('sin-banco', 'no se pudieron preparar los bancos')
 if (benches.failed && benches.failed.length) {
+  // Los bancos de los casos que fallaron, no el del recorrido entero. Nombrar `BENCH_ROOT` se llevaba
+  // por delante los bancos de los casos que nadie estaba re-corriendo: pasó re-midiendo uno solo de
+  // `change-review`, y el mensaje proponía borrar también el del caso vecino. Los ids ya están acá.
   return stop('banco-sin-rehacer',
     `${benches.failed.join(', ')}: su banco conserva trabajo sin recoger de una corrida anterior. ` +
-    `Guardá el registro de esa corrida y volvé a armarlo con --force, o borrá ${BENCH_ROOT}.`)
+    `Guardá el registro de esa corrida y volvé a armarlo con --force, o borrá ` +
+    `${benches.failed.map((id) => `${BENCH_ROOT}/${id}`).join(', ')}.`)
 }
 // Un caso de recorrido gasta el recorrido entero, no dos agentes: de ahí que se diga aparte.
 log(`${context.items.length} caso(s) de ${FLOW} — cada uno corre el recorrido completo`)

package/automatization/workflows/flow.js

@@ -69,9 +69,8 @@ const MANIFEST = {
       id: { type: 'string' }, agent: { type: 'string' }, exitGate: { type: 'string' },
       phase: { type: 'string', enum: ['discovery', 'delivery'] },
       produces: { type: 'array', items: { type: 'string' } },
-      // El recorrido no lo usa —las etapas corren en orden—, pero el contrato lo trae y al agente se le
-      // pide que reporte lo que el comando imprimió. Rechazarlo hacía que el reintento volviera a
-      // copiarlo hasta agotar el cap, y la corrida moría sin haber hecho nada.
+      // El recorrido no lo usa —las etapas corren en orden—, pero el contrato lo trae y el agente lo
+      // copia, así que rechazarlo mataba la corrida por el reintento que se describe en `completion`.
       dependsOn: { type: 'array', items: { type: 'string' } },
       // Resuelto acá una vez: sin esto cada etapa gasta llamadas buscando el contrato de su cargo,
       // que además ya no vive en el proyecto sino en el paquete.
@@ -190,11 +189,11 @@ const owners = (contract.owners || []).map((owner) => `${owner.domain}=${owner.a
 // Qué recorridos existen. Va en las reglas comunes y no sólo en la etapa que enruta: cualquier etapa
 // puede nombrar un destino al cerrar, y son unos pocos slugs. Sin esto `intake` —que existe para
 // enrutar— recomendaba de memoria, que es la conducta que los casos de los cargos castigan.
-const catalogo = (contract.flows || []).filter((slug) => slug !== FLOW)
+const catalog = (contract.flows || []).filter((slug) => slug !== FLOW)
 const RULES = `${BASE}\n\nRecorrido ${contract.name}: ${contract.purpose}\n` +
   `Guardrails: ${contract.guardrails.join(' ')}\n` +
   `${owners ? `Dueños de decisión: ${owners}. Ningún otro cargo resuelve en su dominio.\n` : ''}` +
-  `${catalogo.length ? `Recorridos que existen además de éste: ${catalogo.join(', ')}. Si nombrás un `
+  `${catalog.length ? `Recorridos que existen además de éste: ${catalog.join(', ')}. Si nombrás un `
     + `destino, sale de esa lista; si ninguno sirve, decilo con su razón en vez de inventar uno.\n` : ''}` +
   `Contexto de la empresa en ${WORKDIR}/organization/. Intención a evaluar: ${GOAL}`
 
@@ -219,8 +218,8 @@ function ancestors(stage, index) {
     if (out.has(id)) continue
     out.add(id)
     const found = discovery.find((one) => one.id === id)
-    const arriba = found && found.dependsOn ? found.dependsOn : []
-    for (const up of arriba) pending.push(up)
+    const upstream = found && found.dependsOn ? found.dependsOn : []
+    for (const up of upstream) pending.push(up)
   }
   return [...out]
 }
@@ -250,12 +249,12 @@ function levels(stages) {
 
 const runStage = (stage, index) => {
   const visible = handoffs.filter((entry) => ancestors(stage, index).includes(entry.id))
-  const abiertas = openConditions(visible)
+  const open = openConditions(visible)
   const previous = visible.length
     ? `Handoffs previos:\n${visible.map((entry) => `- ${entry.id}: ${entry.summary}`).join('\n')}`
-      + (abiertas.length
+      + (open.length
         ? '\n\nCondiciones que dejaron las etapas anteriores y tenés que respetar:\n'
-          + abiertas.map((one) => `- ${one}`).join('\n')
+          + open.map((one) => `- ${one}`).join('\n')
         : '')
     : 'Sos la primera etapa: no hay handoff previo.'
   return agent(

package/automatization/workflows/onboard.js

@@ -80,9 +80,8 @@ const SCAN = {
           required: ['kind', 'command', 'source'], properties: {
             kind: { type: 'string' }, command: { type: 'string' }, source: { type: 'string' },
           } } },
-        // Los nombres de variable que ese servicio espera, copiados del inventario. En un multirepo cada
-        // repositorio trae su propio ejemplo, y sin esto las credenciales de tres repos no existían para
-        // el arranque: las filas terminaban diciendo «la credencial del proveedor» sin nombrarla.
+        // Los nombres de variable que ese servicio espera, copiados del inventario y no deducidos: de
+        // acá sale la fila que nombra la credencial en vez de decir «la del proveedor».
         env: { type: 'array', items: { type: 'string' } },
       } } },
     externals: { type: 'array', items: { type: 'string' } },
@@ -144,8 +143,8 @@ if (!CONTEXT && state.opening) {
   return finish({ needsContext: true, opening: state.opening, dimensions, services: services.length })
 }
 
-const INVENTARIO = { services, externals: state.externals || [], secrets: state.secrets || [] }
-const EVIDENCE = `Inventario del workspace:\n${JSON.stringify(INVENTARIO)}` +
+const INVENTORY = { services, externals: state.externals || [], secrets: state.secrets || [] }
+const EVIDENCE = `Inventario del workspace:\n${JSON.stringify(INVENTORY)}` +
   `${CONTEXT ? `\n\nContexto aportado por la persona, que vale como hecho: ${CONTEXT}` : ''}` +
   `${services.length ? '' : '\n\nNo hay ningún servicio en el workspace: el código todavía no está acá.'}`
 

package/engine/agents/evaluations.js

@@ -39,7 +39,7 @@ function caseFiles(dir) {
 //
 // Existe porque un caso que *describe* un artefacto externo sin entregarlo mide algo más fácil de lo
 // que dice medir: al cargo se le pregunta si obedecería un documento del que se le está hablando, y un
-// texto que nunca leyó no puede inyectarlo. Los 47 casos adversariales del catálogo nacieron así, y uno
+// texto que nunca leyó no puede inyectarlo. Los casos adversariales del catálogo nacieron así, y uno
 // produjo un fallo falso: el cargo escribió que había leído una guía inexistente porque el arnés se la
 // había afirmado.
 function fixtureFiles(dir, prefix = '') {
@@ -89,7 +89,7 @@ function list(root, agent, kind) {
   })
 }
 
-// Lo que el cargo no debe hacer, declarado por cargo en `expected-behaviors.yaml`.
+// Lo que el cargo debe y no debe hacer, declarado por cargo en `expected-behaviors.yaml`.
 //
 // Se parsea a mano porque el archivo es una lista de escalares y el repositorio no tiene dependencias:
 // traer un parser de YAML para leer dos listas sería pagar una dependencia por un `split`.
@@ -116,7 +116,8 @@ function behaviors(root, agent, kind) {
 }
 
 // Cuándo cambió por última vez el contrato que la corrida midió. Sale de git y no del mtime del
-// archivo: un `npm ci` o un checkout reescriben mtimes y dirían que todo cambió hoy.
+// archivo: un `npm ci` o un checkout reescriben mtimes y dirían que todo cambió hoy —comprobado con
+// git 2.43.0, un `git checkout <commit> -- <archivo>` le deja el mtime de la corrida—.
 //
 // Sin esto, un contrato que se endurece deja atrás registros que siguen diciendo «pasa» — y el que
 // endurece es justo el que puede hacerlos fallar. Es la misma confusión que el resultado que cubre
@@ -231,17 +232,18 @@ function composed(root, agent, kind) {
   }
 }
 
-// Coherencia entre lo que hay y lo que se corrió. Todo sale como advertencia y ninguno afecta el
-// código de salida, y no es blandura: correr los casos exige un modelo, y CI no lo tiene. Un `evaluate`
-// que fallara por un resultado viejo obligaría a pagar una corrida para poder integrar, y volvería a
-// fallar cada vez que el contrato cambie. Quien falla fuerte es el recorrido que sí los ejecuta.
+// Coherencia entre lo que hay y lo que se corrió. Lo que mide una corrida sale como advertencia y no
+// toca el código de salida, y no es blandura: correr los casos exige un modelo, y CI no lo tiene. Un
+// `evaluate` que fallara por un resultado viejo obligaría a pagar una corrida para poder integrar, y
+// volvería a fallar cada vez que el contrato cambie. Quien falla fuerte es el recorrido que sí los
+// ejecuta. Lo que sí corta con 1 es `errors`, y por qué es la excepción está donde se arma.
 function validate(root, agent, kind) {
   const warnings = []
   const cases = list(root, agent, kind)
   const total = cases.length
   // Esto sí es control estructural y no advertencia: que el artefacto esté entregado es una propiedad
-  // estática del caso, verificable sin modelo, y dejarla en advertencia es lo que permitió que 47 casos
-  // midieran la versión débil de su propia pregunta.
+  // estática del caso, verificable sin modelo, y dejarla en advertencia es lo que permitió que el
+  // catálogo entero midiera la versión débil de su propia pregunta.
   const errors = cases
     .filter((item) => item.id.includes('adversarial') && !item.fixtures.length)
     .map((item) => `${item.id}: caso adversarial sin artefacto en cases/${item.id}/`)
@@ -255,17 +257,17 @@ function validate(root, agent, kind) {
     warnings.push(`sin resultados de casos: corré el recorrido de evaluación para los ${total} casos`)
     return { errors, warnings, cases: total, last: null }
   }
-  const sinMedir = cases.map((item) => item.id).filter((id) => !state.measured.has(id))
-  if (sinMedir.length) {
-    warnings.push(`${state.total} de ${total} caso(s) con veredicto: sin medir ${sinMedir.join(', ')}`)
+  const unmeasured = cases.map((item) => item.id).filter((id) => !state.measured.has(id))
+  if (unmeasured.length) {
+    warnings.push(`${state.total} de ${total} caso(s) con veredicto: sin medir ${unmeasured.join(', ')}`)
   }
   if (state.failed.length) {
     warnings.push(`${state.failed.length} caso(s) no pasan: ${state.failed.join(', ')}`)
   }
-  const cambio = contractChangedAt(subject(root, agent, kind), kind)
-  if (cambio && cambio > state.oldest) {
-    const parte = state.oldest === state.newest ? 'la última corrida es' : 'el veredicto más viejo es'
-    warnings.push(`el contrato cambió el ${cambio} y ${parte} del ${state.oldest}: `
+  const changedAt = contractChangedAt(subject(root, agent, kind), kind)
+  if (changedAt && changedAt > state.oldest) {
+    const which = state.oldest === state.newest ? 'la última corrida es' : 'el veredicto más viejo es'
+    warnings.push(`el contrato cambió el ${changedAt} y ${which} del ${state.oldest}: `
       + 'mide una versión anterior')
   }
   return { errors, warnings, cases: total, last, state }

package/engine/agents/learning-files.js

@@ -0,0 +1,111 @@
+'use strict'
+
+// Los nombres y estados que el ciclo de aprendizaje escribe en disco: cómo se llama un informe y una
+// propuesta, en qué orden se leen, en qué estado están y dónde se puede escribir. Vive aparte porque
+// lo necesitan los dos lados —el ciclo que produce esos documentos y la validación que los juzga— y
+// sin este corte cada uno tendría que requerir al otro.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const catalog = require('./catalog')
+const ownership = require('../core/ownership')
+const { section } = require('../planning/parser')
+
+const REQUIRED_SECTIONS = [
+  'Hallazgos',
+  'Evidencia',
+  'Cambio propuesto',
+  'Riesgos y regresiones',
+  'Evaluación',
+  'Aprobación humana',
+]
+
+// 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.
+// Un recorrido no viene del paquete cuando lo mantiene este repositorio, así que la pregunta de
+// dónde se puede escribir es la misma y la respuesta se resuelve igual: dentro del proyecto, sí.
+function assertWritableTeam(root, slug) {
+  const dir = path.dirname(require('../flows/registry').read(root, slug).file)
+  const own = path.resolve(root, 'flows')
+  if (path.resolve(dir).startsWith(`${own}${path.sep}`)) return dir
+  throw new Error(
+    `${slug} es un recorrido que trae Cauce y su aprendizaje se hace en el toolkit, no acá.\n` +
+    `  Para tener una versión propia, copialo a flows/${slug}/ y mantenelo vos.`,
+  )
+}
+
+function assertWritable(root, agent, kind = 'agent') {
+  if (kind === 'flow') return assertWritableTeam(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, adoptalo: ops agents fork ${agent}.`,
+  )
+}
+
+function isoDate(now = new Date()) { return now.toISOString().slice(0, 10) }
+function month(now = new Date()) { return now.toISOString().slice(0, 7) }
+
+// Una propuesta por período, y sus revisiones. La revisión existe porque aplicar no es el final del
+// ciclo: la evaluación posterior es la que dice si el cambio sirvió, y cuando dice que no, el sello
+// —que está para que nadie reaplique lo mismo y duplique cada viñeta— dejaba al cargo con un contrato
+// que se sabe mal calibrado y sin camino para corregirlo hasta el mes siguiente. La corrección es un
+// cambio distinto: documento propio, firma propia, y la aplicada queda sellada donde está.
+const PROPOSAL_NAME = /^(\d{4}-\d{2})(?:-r(\d+))?\.md$/
+
+// Mismo cuidado que con los registros de evaluación: `-` va antes que `.` en ASCII, así que ordenar
+// nombres pondría `2026-08-r2.md` delante de `2026-08.md` y la revisión se leería como la más vieja.
+function proposalOrder(name) {
+  const [, period, revision] = name.match(PROPOSAL_NAME)
+  return `${period}-${String(Number(revision || 1)).padStart(4, '0')}`
+}
+
+// El tope de la línea de índice. No es estético: es una línea por cargo, todas a la vez, y una que se
+// envuelve rompe la columna que hace posible el vistazo.
+const SUMMARY_MAX = 120
+
+function proposalFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .filter((name) => PROPOSAL_NAME.test(name))
+      .sort((one, other) => proposalOrder(one).localeCompare(proposalOrder(other)))
+  } catch { return [] }
+}
+
+function frontmatterState(text, fallback) {
+  return ((text.match(/^status:\s*(\S+)\s*$/m) || [])[1] || fallback).toLowerCase()
+}
+
+function proposalState(text) {
+  return frontmatterState(text, 'proposed')
+}
+
+// El sufijo `-N` es la segunda corrida del mismo día, y es la que trae el veredicto más nuevo. Sin él
+// en el patrón, más de una cuarta parte de los registros que existían —de cargos y de recorridos—
+// quedaban fuera del ciclo: no entraban a ninguna propuesta y nada lo delataba, que es el modo de fallo
+// que el comentario de `markConsolidated` ya describía para el informe atrasado.
+const REPORT_NAME = /^(\d{4}-\d{2}-\d{2})(?:-(\d+))?\.md$/
+
+function reportFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .map((name) => [name, REPORT_NAME.exec(name)])
+      .filter(([, hit]) => hit)
+      .sort(([, a], [, b]) =>
+        (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : Number(a[2] || 0) - Number(b[2] || 0)))
+      .map(([name]) => name)
+  } catch { return [] }
+}
+
+module.exports = {
+  REQUIRED_SECTIONS, SUMMARY_MAX, PROPOSAL_NAME, REPORT_NAME,
+  assertWritableTeam, assertWritable, isoDate, month,
+  proposalOrder, proposalFiles, frontmatterState, proposalState, reportFiles,
+}

package/engine/agents/learning-sources.js

@@ -0,0 +1,166 @@
+'use strict'
+
+// El contrato de fuentes de un cargo y la validación que lo mide: qué tipos hay, cada cuánto le toca
+// investigar a quien las declara, y qué está mal escrito. Su reloj es el del contrato —un tipo nuevo,
+// otra cadencia—, no el del ciclo que produce informes y propuestas.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const catalog = require('./catalog')
+const evaluations = require('./evaluations')
+const {
+  REQUIRED_SECTIONS, SUMMARY_MAX, frontmatterState, proposalFiles, proposalState, reportFiles,
+} = require('./learning-files')
+
+function evaluateTeam(root, slug) {
+  const dir = path.dirname(require('../flows/registry').read(root, slug).file)
+  const errors = []
+  const warnings = []
+  if (!fs.existsSync(path.join(dir, 'learning', 'HISTORY.md'))) {
+    warnings.push('sin learning/HISTORY.md: lo que se le cambie al recorrido no queda registrado')
+  }
+  const proposals = proposalFiles(path.join(dir, 'learning', 'proposals'))
+  let pending = 0
+  for (const name of proposals) {
+    const text = fs.readFileSync(path.join(dir, 'learning', 'proposals', name), 'utf8')
+    if (!/^automatic_apply:\s*false$/m.test(text)) errors.push(`${name}: automatic_apply debe ser false`)
+    for (const section of REQUIRED_SECTIONS) {
+      if (!text.includes(`## ${section}`)) errors.push(`${name}: falta sección ${section}`)
+    }
+    if (proposalState(text) !== 'applied') pending += 1
+  }
+  return { errors, warnings, proposals: proposals.length, pending, cases: 0 }
+}
+
+// Qué publica una fuente, que es lo único que decide cada cuánto vale la pena volver a mirarla. No
+// dice si es primaria —eso lo exige `rules.require_primary_source`— ni si sigue vigente: lo que se
+// aparta del default lo declara la fuente con `authority:` o `status:`, y por eso son dos campos y no
+// un nombre compuesto. Cuando eran uno solo el catálogo llegó a 51 etiquetas para estas seis.
+const SOURCE_TIERS = ['advisory', 'platform', 'project', 'regulation', 'standard', 'profession']
+
+// Cada cuánto vale la pena volver a mirar cada tipo. Un aviso publica todos los días y llegar un mes
+// tarde es llegar tarde; una norma se revisa por edición y mirarla cada lunes devuelve el mismo texto.
+// La cadencia de un cargo la fija su fuente más rápida: basta una que corra para que la semana traiga
+// algo, y ninguna otra pierde nada por mirarse antes.
+const TIER_CADENCE = {
+  advisory: 'semanal', platform: 'semanal', project: 'semanal',
+  regulation: 'mensual', standard: 'mensual', profession: 'trimestral',
+}
+const CADENCES = ['semanal', 'mensual', 'trimestral']
+
+// Sale del árbol y no de una lista escrita a mano, por la misma razón que la matriz del cron sale del
+// árbol: una lista paralela se pudre el día que un cargo cambia sus fuentes y nadie la toca.
+function cadence(root, agent) {
+  const file = path.join(catalog.resolve(root, agent), 'learning', 'sources.yaml')
+  if (!fs.existsSync(file)) return ''
+  const tiers = sourceTiers(fs.readFileSync(file, 'utf8')).filter((one) => TIER_CADENCE[one])
+  if (!tiers.length) return ''
+  return CADENCES[Math.min(...tiers.map((one) => CADENCES.indexOf(TIER_CADENCE[one])))]
+}
+
+// Basta con las líneas `tier:`: el archivo es del catálogo, no de un tercero, y agregar un parser de
+// YAML por un campo rompería la regla de cero dependencias.
+function sourceTiers(text) {
+  const body = text.includes('sources:') ? text.slice(text.indexOf('sources:')) : ''
+  return [...body.matchAll(/tier:\s*([A-Za-z-]+)/g)].map((hit) => hit[1])
+}
+
+// Las fuentes de un cargo, por su URL. La misma URL con dos nombres es una sola fuente contada dos
+// veces: el catálogo llegó a tener la especificación OpenAPI bajo tres —`OpenAPI Specification`,
+// `...latest published` y `...3.2.0`— así que arreglarle el `tier` a un cargo no se lo arreglaba a los
+// otros, y quien leyera el informe vería la misma página citada como si fueran tres.
+function sourceUrls(text) {
+  const body = text.includes('sources:') ? text.slice(text.indexOf('sources:')) : ''
+  const out = []
+  let name = ''
+  for (const line of body.split('\n')) {
+    const declared = line.match(/^\s*-\s*name:\s*(.+?)\s*$/)
+    if (declared) { name = declared[1].replace(/^['"]|['"]$/g, ''); continue }
+    const url = line.match(/^\s*url:\s*(\S+)/)
+    if (url && name) out.push({ name, url: url[1].replace(/\/+$/, '') })
+  }
+  return out
+}
+
+function evaluate(root, agent) {
+  const target = catalog.resolve(root, agent)
+  const errors = []
+  const warnings = []
+  const requiredFiles = [
+    'learning/sources.yaml',
+    'learning/HISTORY.md',
+    'evaluations/expected-behaviors.yaml',
+  ]
+  // `AUTOMATION.md` documenta cómo corre la automatización de aprendizaje del toolkit. Exigírselo
+  // a una empresa que escribe un cargo propio era pedirle contabilidad interna nuestra: su cargo debe
+  // tener contrato, fuentes e historia, no nuestro andamiaje.
+  if (catalog.find(root, agent).system) requiredFiles.push('learning/AUTOMATION.md')
+  for (const relative of requiredFiles) {
+    if (!fs.existsSync(path.join(target, relative))) errors.push(`falta ${relative}`)
+  }
+  const sourcesFile = path.join(target, 'learning', 'sources.yaml')
+  if (fs.existsSync(sourcesFile)) {
+    const tiers = sourceTiers(fs.readFileSync(sourcesFile, 'utf8'))
+    // Sin fuentes el ciclo semanal no tiene literatura que leer y devuelve un informe vacío cada
+    // semana. Avisa y no bloquea: un cargo que se está escribiendo todavía no las tiene.
+    if (!tiers.length) warnings.push('sources.yaml sin fuentes: la investigación no tiene qué leer')
+    for (const tier of tiers) {
+      if (!SOURCE_TIERS.includes(tier)) {
+        errors.push(`sources.yaml: tier "${tier}" fuera de ${SOURCE_TIERS.join(' | ')}`)
+      }
+    }
+    // Dos nombres para una URL. Es error y no aviso: la cadencia sale del `tier` de cada entrada, así
+    // que dos copias de la misma fuente pueden decir cosas distintas sobre cada cuánto publica, y la
+    // más rápida gana sin que nadie lo haya decidido.
+    const byUrl = new Map()
+    for (const one of sourceUrls(fs.readFileSync(sourcesFile, 'utf8'))) {
+      const previous = byUrl.get(one.url)
+      if (previous && previous !== one.name) {
+        errors.push(`sources.yaml: ${one.url} está dos veces, como "${previous}" y como "${one.name}"`)
+      }
+      byUrl.set(one.url, one.name)
+    }
+  }
+  const skill = fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8').toLowerCase()
+  for (const phrase of ['no inventar', 'autorización', 'evidencia observable']) {
+    if (!skill.includes(phrase)) errors.push(`SKILL.md no conserva el control: ${phrase}`)
+  }
+  // Sin su línea, el cargo existe pero no se encuentra: quien tiene una tarea tendría que abrir la
+  // carpeta para saber si es éste. Se exige acá y no como advertencia porque es estático y de una línea.
+  const summary = catalog.summary(target)
+  if (!summary) errors.push('SKILL.md no declara summary: la línea con la que se elige este cargo')
+  else if (summary.length > SUMMARY_MAX) {
+    errors.push(`summary tiene ${summary.length} caracteres y el máximo es ${SUMMARY_MAX}: `
+      + 'si no entra en una línea, no sirve para elegir de un vistazo')
+  }
+  const proposals = proposalFiles(path.join(target, 'learning', 'proposals'))
+  let pending = 0
+  for (const name of proposals) {
+    const text = fs.readFileSync(path.join(target, 'learning', 'proposals', name), 'utf8')
+    if (!/^automatic_apply:\s*false$/m.test(text)) errors.push(`${name}: automatic_apply debe ser false`)
+    for (const section of REQUIRED_SECTIONS) {
+      if (!text.includes(`## ${section}`)) errors.push(`${name}: falta sección ${section}`)
+    }
+    // Contar sólo las que esperan algo. Una propuesta aplicada contada como propuesta deja al cargo
+    // reportando trabajo pendiente para siempre, y es la misma confusión que permitía reaplicarla.
+    if (proposalState(text) !== 'applied') pending += 1
+  }
+  // Los hallazgos que todavía no llegaron al contrato. No es un error —la propuesta que los tome
+  // puede no haberse abierto aún—, pero sin decirlo un informe escrito y olvidado se ve igual que uno
+  // ya incorporado: los dos son un archivo en `reports/`.
+  const reportDir = path.join(target, 'learning', 'reports')
+  const unconsolidated = reportFiles(reportDir).filter((name) =>
+    frontmatterState(fs.readFileSync(path.join(reportDir, name), 'utf8'), 'draft') !== 'consolidated')
+  if (unconsolidated.length) {
+    warnings.push(`${unconsolidated.length} informe(s) sin consolidar (${unconsolidated.join(', ')}): `
+      + 'entran en la próxima propuesta')
+  }
+  let cases = 0
+  try {
+    cases = fs.readdirSync(path.join(target, 'evaluations', 'cases'))
+      .filter((name) => name.endsWith('.md')).length
+  } catch { /* vacío */ }
+  return { errors, warnings, proposals: proposals.length, pending, cases }
+}
+
+module.exports = { SOURCE_TIERS, CADENCES, cadence, evaluate, evaluateTeam }