@ingeniomaps/cauce 0.52.0 → 0.53.1

package/engine/agents/learning.js

@@ -7,102 +7,11 @@ const { atomicWrite } = require('../core/files')
 // La misma lectura de secciones que usa el planning: repetirla acá sería una segunda copia del mismo
 // hecho, y una de las dos se pudre sin que nada falle (R11).
 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: son 47 líneas que se leen de un vistazo, 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, 51 de los 188 registros que hoy existen —44 de cargos, 7 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.
-//
-// Ordenar por nombre no alcanza: `-` (0x2D) es menor que `.` (0x2E), así que `2026-08-24-2.md` cae
-// antes que `2026-08-24.md` y la corrida más nueva se leería primero.
-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 [] }
-}
+const {
+  REQUIRED_SECTIONS, SUMMARY_MAX, PROPOSAL_NAME, REPORT_NAME, assertWritableTeam, assertWritable,
+  isoDate, month, proposalOrder, proposalFiles, frontmatterState, proposalState, reportFiles,
+} = require('./learning-files')
+const { SOURCE_TIERS, CADENCES, cadence, evaluate, evaluateTeam } = require('./learning-sources')
 
 // El informe que ya entró a una propuesta. Nace en `draft` y nada lo movía nunca, así que el que se
 // consolidó y el que se escribió tarde —después de que la propuesta del período ya existía, y por eso
@@ -230,10 +139,17 @@ propuesta consolidada. -->
 // propuesta que ésta corrige, y repetirlos haría que el mismo hallazgo entre dos veces al contrato. El
 // insumo de una revisión es otro —qué mostró la evaluación posterior a aplicar—, y por eso el molde
 // pregunta eso y no otra cosa.
-function reviseProposal(root, agent, dir, previous, period) {
+//
+// El molde de los apartados que una persona escribe queda; lo que deja de quedar es `## Hallazgos` en
+// blanco. Una revisión que no puede decir qué la motiva no puede producir un cambio, y hasta acá se
+// llega sólo con material: el llamador ya se negó a abrirla sin él.
+function reviseProposal(root, agent, dir, previous, period, findings = [], consumed = []) {
   const parsed = previous.match(PROPOSAL_NAME)
   const revision = Number(parsed[2] || 1) + 1
   const file = path.join(dir, `${period}-r${revision}.md`)
+  const placeholder = `Qué mostró la evaluación posterior a aplicar \`${previous}\`. No repitas acá los hallazgos de esa
+propuesta —ya entraron al contrato—: lo que va es lo que se supo después, con el registro de
+evaluación que lo sostiene.`
   fs.writeFileSync(file, `---
 agent: ${agent}
 period: ${period}
@@ -250,9 +166,7 @@ la reabre: es un cambio distinto, con su propia firma.
 
 ## Hallazgos
 
-Qué mostró la evaluación posterior a aplicar \`${previous}\`. No repitas acá los hallazgos de esa propuesta
-—ya entraron al contrato—: lo que va es lo que se supo después, con el registro de evaluación que lo
-sostiene.
+${findings.join('\n\n') || placeholder}
 
 ## Evidencia
 
@@ -281,7 +195,8 @@ sólo que pase.
 - Responsable: por definir
 - Fecha: por definir
 `)
-  return { file, created: true, reports: 0, corrects: previous }
+  for (const record of consumed) markConsolidated(record)
+  return { file, created: true, reports: 0, corrects: previous, findings: findings.length }
 }
 
 // La última propuesta del período, si la hay: es contra ella que se decide si abrir una revisión.
@@ -290,18 +205,9 @@ function lastOfPeriod(dir, period) {
   return names.length ? names[names.length - 1] : ''
 }
 
-// La propuesta se llama por el mes en que se abre, y `period` sólo existe para una corrida a mano
-// sobre otro mes. El ciclo automático no lo usa: nombrarle el mes que cerró abriría una **revisión**
-// —lo que se abre cuando ese mes ya tiene una propuesta aplicada—, y corregir es un acto humano.
-// Lo que hace que ningún informe se pierda no es el nombre sino el criterio de más abajo.
-// Qué aprende un recorrido, y de dónde. Un cargo aprende de su profesión —normas, versiones, fuentes
-// que cambian afuera— y por eso investiga. Un recorrido no tiene profesión: lo único que puede
-// enseñarle algo es cómo le fue, así que su insumo son los veredictos en contra de sus propias
-// corridas. Pedirle una investigación semanal sería pedirle que lea una literatura que no existe, y
-// devolvería informes vacíos.
-//
-// De cada registro sin sellar entran los casos que no pasaron, con su contraste y de qué corrida
-// salen. Si no hay ninguno, eso también es un resultado: el recorrido aguantó y no hay qué corregir.
+// De qué aprende un recorrido: de cada registro sin sellar entran los casos que no pasaron, con su
+// contraste y de qué corrida salen. Si no hay ninguno, eso también es un resultado — el recorrido
+// aguantó y no hay qué corregir. Por qué es esto y no una investigación, en `pendingRuns`.
 const VERDICT = /\n### ([^\n]+)\n\n- Veredicto: (pasa|no pasa)\n([\s\S]*?)(?=\n### |$)/g
 
 function verdicts(text) {
@@ -320,7 +226,11 @@ function verdicts(text) {
 //
 // Cuántas veces falló sí viaja, porque no es lo mismo un rojo suelto que uno que aguantó dos arreglos
 // distintos: lo primero puede ser varianza y lo segundo es una medición estable.
-function flowFindings(root, dir) {
+//
+// Sirve a los dos, y no por generalidad: el formato del registro es el mismo —`### caso` y
+// `- Veredicto:`— porque lo escribe el mismo `evaluate --record`. Un cargo tenía este material desde
+// siempre y nada lo leía, así que aprendía de su profesión y no de haber fallado su propia medición.
+function verdictFindings(root, dir) {
   const results = path.join(dir, 'evaluations', 'results')
   const unsealed = reportFiles(results).filter((name) =>
     frontmatterState(fs.readFileSync(path.join(results, name), 'utf8'), 'draft') !== 'consolidated')
@@ -349,13 +259,26 @@ function pendingRuns(root, slug) {
     frontmatterState(fs.readFileSync(path.join(results, name), 'utf8'), 'draft') !== 'consolidated').length
 }
 
+// El espejo del anterior para un cargo: qué informes esperan entrar a una propuesta. Toma todo lo que
+// ya ocurrió y todavía no entró, no sólo lo del mes que se consolida. Filtrar por el prefijo del
+// período dejaba huérfano al informe atrasado —el que se escribió después de que su mes se consolidó,
+// o el que llegó tarde—: no entraba en ésa ni en ninguna posterior, porque la del mes siguiente sólo
+// miraba su propio mes. Se perdía el hallazgo entero y en silencio.
+//
+// Repetirlo no es un riesgo: el sello dice cuál ya entró, y por eso este criterio existe recién ahora.
+// Antes todos decían `draft` y no había cómo distinguirlos.
+function pendingReports(target, sealing) {
+  const dir = path.join(target, 'learning', 'reports')
+  return reportFiles(dir).filter((name) => name.slice(0, 7) <= sealing
+    && frontmatterState(fs.readFileSync(path.join(dir, name), 'utf8'), 'draft') !== 'consolidated')
+}
+
 // La propuesta de un recorrido. Mismo ciclo que la de un cargo —se abre, se firma, se aplica y se
 // sella— y distinto contenido: lo que se corrige es el recorrido mismo, y lo que lo justifica es un
 // veredicto en contra, no una fuente nueva.
-function proposeFromRuns(root, agent, target, file, period) {
-  const { consumed, findings } = flowFindings(root, target)
-  const empty = 'Ninguna corrida sin consolidar dejó un veredicto en contra. El recorrido '
-    + 'aguantó lo que se le midió, y eso no pide cambio.'
+// Recibe los hallazgos ya compuestos: el llamador los necesita antes para decidir si abre documento,
+// y volver a leerlos acá sería leer dos veces lo mismo para responder la misma pregunta.
+function proposeFromRuns(root, agent, target, file, period, { consumed, findings }) {
   fs.writeFileSync(file, `---
 flow: ${agent}
 period: ${period}
@@ -367,7 +290,7 @@ automatic_apply: false
 
 ## Hallazgos
 
-${findings.join('\n\n') || empty}
+${findings.join('\n\n')}
 
 ## Evidencia
 
@@ -399,6 +322,10 @@ Qué caso tiene que cambiar de veredicto y por qué razón, no sólo que la corr
   return { file, created: true, reports: consumed.length, findings: findings.length }
 }
 
+// La propuesta se llama por el mes en que se abre, y `period` sólo existe para una corrida a mano
+// sobre otro mes. El ciclo automático no lo usa: nombrarle el mes que cerró abriría una **revisión**
+// —lo que se abre cuando ese mes ya tiene una propuesta aplicada—, y corregir es un acto humano.
+// Lo que hace que ningún informe se pierda no es el nombre sino el criterio de `pendingReports`.
 function prepareProposal(root, agent, now = new Date(), period = '', kind = 'agent') {
   if (period && !/^\d{4}-\d{2}$/.test(period)) throw new Error(`período inválido: ${period}`)
   const target = assertWritable(root, agent, kind)
@@ -409,40 +336,44 @@ function prepareProposal(root, agent, now = new Date(), period = '', kind = 'age
   // Una sola propuesta pendiente por período. Si la última todavía no se aplicó, abrir otra partiría
   // la firma en dos documentos que dicen cosas distintas sobre el mismo contrato.
   const previous = lastOfPeriod(proposalDir, sealing)
-  if (previous) {
-    const before = path.join(proposalDir, previous)
-    if (proposalState(fs.readFileSync(before, 'utf8')) !== 'applied') {
-      return { file: before, created: false, reports: 0 }
-    }
-    return reviseProposal(root, agent, proposalDir, previous, sealing)
+  const unapplied = previous && proposalState(fs.readFileSync(path.join(proposalDir, previous), 'utf8')) !== 'applied'
+  if (unapplied) return { file: path.join(proposalDir, previous), created: false, reports: 0 }
+
+  // La misma regla que abajo, y el mismo motivo: un documento que no puede decir qué corregir no
+  // produce un cambio de contrato, y cuesta igual la firma humana que uno que sí. Antes se abría uno
+  // por recorrido con corridas sin sellar aunque todas hubieran pasado, para decir que no había nada.
+  //
+  // Lo que se pierde es el sello de esas corridas, y es inocuo: los hallazgos se componen por caso con
+  // la última corrida ganando, así que una verde vieja no cambia ningún veredicto. Lo único que queda
+  // es que el recorrido siga contándose en `pending` y su job vuelva a no encontrar nada.
+  if (kind === 'flow') {
+    const red = verdictFindings(root, target)
+    if (!red.findings.length) return { file: '', created: false, reports: 0 }
+    if (previous) return reviseProposal(root, agent, proposalDir, previous, sealing, red.findings, red.consumed)
+    return proposeFromRuns(root, agent, target, path.join(proposalDir, `${sealing}.md`), sealing, red)
   }
 
-  const file = path.join(proposalDir, `${sealing}.md`)
-  if (kind === 'flow') return proposeFromRuns(root, agent, target, file, sealing)
-  const reportDir = path.join(target, 'learning', 'reports')
-  // Todo lo que ya ocurrió y todavía no entró, no sólo lo del mes que se consolida. Filtrar por el
-  // prefijo del período dejaba huérfano al informe atrasado —el que se escribió después de que su mes
-  // se consolidó, o el que llegó tarde—: no entraba en ésa ni en ninguna posterior, porque la del mes
-  // siguiente sólo miraba su propio mes. Se perdía el hallazgo entero y en silencio.
+  // Los dos materiales de un cargo, y dicen cosas distintas: un informe sin consolidar dice que cambió
+  // la profesión, un caso en rojo dice que el contrato no se sostuvo. Cualquiera de los dos puede
+  // cambiarlo, así que cualquiera de los dos abre documento.
   //
-  // Repetirlo no es un riesgo: el sello dice cuál ya entró, y por eso este criterio existe recién
-  // ahora. Antes todos decían `draft` y no había cómo distinguirlos.
-  const reports = reportFiles(reportDir).filter((name) => name.slice(0, 7) <= sealing
-    && frontmatterState(fs.readFileSync(path.join(reportDir, name), 'utf8'), 'draft') !== 'consolidated')
-  // El cron lo dice antes que nadie: consolidar sin informes produce un andamiaje que nadie puede
-  // aprobar, y el job ve un archivo nuevo y abre el PR igual. Con una cadencia por cargo eso deja de
-  // ser un borde: el que investiga cada trimestre pasaría dos meses de cada tres abriendo propuestas
-  // para decir que no investigó.
-  if (!reports.length) return { file: '', created: false, reports: 0 }
-  const summaries = reports.map((name) => {
-    const report = path.join(reportDir, name)
-    const text = fs.readFileSync(report, 'utf8')
-    // Sin `m`: con esa bandera el `$` casa fin de *línea*, así que la búsqueda no ávida cortaba en el
-    // primer salto y la propuesta consolidaba una sola línea de una recomendación de diez.
-    const match = text.match(/\n## Recomendación\s*\n([\s\S]*?)(?=\n## |$)/) || []
-    const recommendation = (match[1] || 'Sin recomendación registrada.').trim()
-    return `### ${name.slice(0, -3)}\n\nFuente interna: \`${path.relative(root, report)}\`\n\n${recommendation}`
-  })
+  // Sin ninguno no se abre nada, y por eso la guarda vive acá arriba en vez de debajo de la
+  // bifurcación, que es donde cubría sólo la propuesta del período: la revisión se fabricaba igual
+  // para todo cargo cuya propuesta anterior estuviera aplicada. Que sea un andamio en blanco no la
+  // abarata —cuesta la misma firma humana— y encima llega indistinguible de una con hallazgos en la
+  // lista de PR. Componer el documento desde el material lo vuelve imposible en vez de prohibido.
+  const reportDir = path.join(target, 'learning', 'reports')
+  const reports = pendingReports(target, sealing)
+  const red = verdictFindings(root, target)
+  if (!reports.length && !red.findings.length) return { file: '', created: false, reports: 0 }
+
+  const reportPaths = reports.map((name) => path.join(reportDir, name))
+  const findings = [...reportPaths.map((file) => reportSummary(root, file)), ...red.findings]
+  const consumed = [...reportPaths, ...red.consumed]
+  if (previous) return reviseProposal(root, agent, proposalDir, previous, sealing, findings, consumed)
+
+  const file = path.join(proposalDir, `${sealing}.md`)
+  const summaries = findings
   fs.writeFileSync(file, `---
 agent: ${agent}
 period: ${sealing}
@@ -478,132 +409,22 @@ Pendiente.
 - Responsable: por definir
 - Fecha: por definir
 `)
-  for (const name of reports) markConsolidated(path.join(reportDir, name))
-  return { file, created: true, reports: reports.length }
-}
-
-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])))]
+  for (const record of consumed) markConsolidated(record)
+  return { file, created: true, reports: reports.length, findings: red.findings.length }
 }
 
-// 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])
+// La recomendación de un informe, que es lo único que la propuesta consolida de él.
+function reportSummary(root, report) {
+  const name = path.basename(report)
+  const text = fs.readFileSync(report, 'utf8')
+  // Sin `m`: con esa bandera el `$` casa fin de *línea*, así que la búsqueda no ávida cortaba en el
+  // primer salto y la propuesta consolidaba una sola línea de una recomendación de diez. Comprobado en
+  // node v24.18.0: el mismo patrón con `m` devuelve la primera línea y sin `m` devuelve el bloque.
+  const match = text.match(/\n## Recomendación\s*\n([\s\S]*?)(?=\n## |$)/) || []
+  const recommendation = (match[1] || 'Sin recomendación registrada.').trim()
+  return `### ${name.slice(0, -3)}\n\nFuente interna: \`${path.relative(root, report)}\`\n\n${recommendation}`
 }
 
-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(' | ')}`)
-      }
-    }
-  }
-  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,

package/engine/automation/config.js

@@ -0,0 +1,175 @@
+'use strict'
+
+// Cómo se fusiona y se retira lo nuestro dentro de un archivo del usuario: la configuración del runner
+// y el bloque enmarcado de un `AGENTS.md` compartido. Es una sola pregunta —qué entregamos y cómo se
+// saca sin llevarse lo ajeno— y cambia cuando cambia el formato de esos archivos, no cuando cambia un
+// comando.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const F = require('../core/files')
+const { supersededGuards } = require('./hooks')
+
+function mergeConfig(current, incoming) {
+  if (Array.isArray(incoming)) {
+    const values = [...(Array.isArray(current) ? current : []), ...incoming]
+    const seen = new Set()
+    return values.filter((value) => {
+      const key = JSON.stringify(value)
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+  }
+  if (incoming && typeof incoming === 'object') {
+    const object = current && typeof current === 'object' && !Array.isArray(current)
+    const result = object ? { ...current } : {}
+    for (const [key, value] of Object.entries(incoming)) {
+      result[key] = mergeConfig(result[key], value)
+    }
+    return result
+  }
+  return incoming
+}
+
+// Una entrada de hook que puso Cauce se reconoce por el guard al que apunta: `automatization/hooks/`
+// es nuestro y ninguna empresa escribe ahí. Se saca del archivo del usuario antes de fusionar para que
+// el merge deje exactamente las de esta versión, ni una más.
+const DELIVERED = /automatization\/hooks\/guard-[a-z-]+\.sh/
+
+function withoutDeliveredHooks(config, live) {
+  const dropped = []
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      return node
+        .filter((item) => {
+          const command = item && typeof item === 'object' ? String(item.command || '') : ''
+          if (!DELIVERED.test(command)) return true
+          // Sólo se anuncia lo que ya no vuelve: una entrada que el merge repone quedó igual, y decir
+          // que se quitó y se puso la misma línea es ruido que esconde el caso que sí importa.
+          if (!live.has(command)) dropped.push(command)
+          return false
+        })
+        .map(walk)
+        .filter((item) => !(item && typeof item === 'object' && Array.isArray(item.hooks) && !item.hooks.length))
+    }
+    if (node && typeof node === 'object') {
+      return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, walk(value)]))
+    }
+    return node
+  }
+  return { config: walk(config), dropped }
+}
+
+// Por qué se fue cada entrada nuestra. Un guard suelto que ahora cubre un grupo no es lo mismo que una
+// ruta que dejó de existir: el primero se ejecutaba dos veces por herramienta —con `verify`, la suite
+// entera del proyecto dos veces por commit—, y el segundo no se ejecutaba nunca. Decirlo distinto es lo
+// único que le permite a alguien darse cuenta de cuál de los dos tenía.
+function reportRemoved(name, dropped, live, output) {
+  const wrappers = new Map()
+  const loose = []
+  for (const command of dropped) {
+    const hit = supersededGuards().find(
+      (entry) => command.endsWith(entry.file) && [...live].some((v) => v.endsWith(entry.wrapper)),
+    )
+    if (hit) wrappers.set(hit.wrapper, [...(wrappers.get(hit.wrapper) || []), hit.file])
+    else loose.push(command)
+  }
+  for (const [wrapper, files] of wrappers) {
+    output.log(`− ${name}: reemplazado ${[...new Set(files)].join(', ')} por ${wrapper}`)
+  }
+  for (const command of loose) output.log(`− ${name}: quitada una entrada obsoleta (${command})`)
+}
+
+function includesConfig(actual, expected) {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && expected.every((item) => {
+      return actual.some((value) => JSON.stringify(value) === JSON.stringify(item))
+    })
+  }
+  if (expected && typeof expected === 'object') {
+    return actual && typeof actual === 'object' && Object.entries(expected).every(([key, value]) => {
+      return includesConfig(actual[key], value)
+    })
+  }
+  return actual === expected
+}
+
+function hasHooks(config) {
+  if (config.hooks && Object.keys(config.hooks).length) return true
+  const events = [
+    'PreToolUse',
+    'PostToolUse',
+    'PreInvocation',
+    'PostInvocation',
+    'Stop',
+    'SessionEnd',
+  ]
+  return Object.values(config).some((entry) => {
+    return entry && typeof entry === 'object' && events.some((event) => event in entry)
+  })
+}
+
+// Quita de una estructura de configuración exactamente lo que este adaptador habría puesto, y nada más.
+// Es el inverso de `mergeConfig`: una entrada del usuario nunca coincide literalmente con la nuestra, así
+// que sobrevive; una que editó tampoco coincide, y por eso se conserva y se avisa en vez de borrarse.
+function unmergeConfig(current, incoming) {
+  if (Array.isArray(incoming)) {
+    if (!Array.isArray(current)) return current
+    const ours = new Set(incoming.map((value) => JSON.stringify(value)))
+    return current.filter((value) => !ours.has(JSON.stringify(value)))
+  }
+  if (incoming && typeof incoming === 'object') {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) return current
+    const result = { ...current }
+    for (const [key, value] of Object.entries(incoming)) {
+      if (!(key in result)) continue
+      const clean = unmergeConfig(result[key], value)
+      // Una clave que queda vacía por habernos ido no es del usuario: la creamos nosotros al instalar.
+      const empty = clean === undefined
+        || (Array.isArray(clean) && !clean.length)
+        || (clean && typeof clean === 'object' && !Array.isArray(clean) && !Object.keys(clean).length)
+      if (empty) delete result[key]
+      else result[key] = clean
+    }
+    return result
+  }
+  return JSON.stringify(current) === JSON.stringify(incoming) ? undefined : current
+}
+
+const blockStart = (name) => `<!-- cauce:${name} inicio — lo reescribe "automation install", no editar -->`
+const blockEnd = (name) => `<!-- cauce:${name} fin -->`
+
+function isSharedFile(root, target) {
+  return path.resolve(target) === path.resolve(root, 'AGENTS.md')
+}
+
+function withoutBlock(text, name) {
+  const sourceRoot = text.indexOf(blockStart(name))
+  if (sourceRoot === -1) return text
+  const until = text.indexOf(blockEnd(name), sourceRoot)
+  if (until === -1) return text
+  return `${text.slice(0, sourceRoot)}${text.slice(until + blockEnd(name).length)}`.trimEnd()
+}
+
+function mergeInstruction(file, name, content) {
+  const actual = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+  const instructionBody = withoutBlock(actual, name).trimEnd()
+  const block = `${blockStart(name)}\n\n${content.trim()}\n\n${blockEnd(name)}\n`
+  F.atomicWrite(file, instructionBody ? `${instructionBody}\n\n${block}` : block)
+}
+
+function blockUpToDate(file, name, content) {
+  if (!fs.existsSync(file)) return false
+  const body = fs.readFileSync(file, 'utf8')
+  const sourceRoot = body.indexOf(blockStart(name))
+  const until = body.indexOf(blockEnd(name))
+  if (sourceRoot === -1 || until === -1) return false
+  return body.slice(sourceRoot + blockStart(name).length, until).trim() === content.trim()
+}
+
+module.exports = {
+  blockStart,
+  mergeConfig, withoutDeliveredHooks, reportRemoved, includesConfig, hasHooks,
+  unmergeConfig, isSharedFile, withoutBlock, mergeInstruction, blockUpToDate,
+}