@ingeniomaps/cauce 0.53.0 → 0.53.2

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 }