@ingeniomaps/cauce 0.68.0 → 0.70.0

package/engine/planning/parser.js

@@ -193,6 +193,31 @@ function acceptanceConditions(value) {
   return text.split(';').map((one) => one.trim()).filter(Boolean).length
 }
 
+// Una línea de tarea, leída en un solo lugar: `readBacklog` la usa para armar la cola y `recurring.js`
+// para juzgar la línea que va a emitir. Es el mismo motivo por el que `TASK_LINE` no está duplicado —
+// lo que emite una y lee la otra tiene que ser la misma forma, o el emisor produce lo que el lector
+// descarta.
+function taskFromLine(line) {
+  const task = line.match(TASK_LINE)
+  if (!task) return null
+  const rest = task[3]
+  const acceptance = ((rest.match(ACCEPTANCE) || [])[1] || '').trim()
+  return {
+    slug: task[1].trim(), tier: task[2] || '', cast: readCast(rest),
+    epic: ((rest.match(/\(epic:\s*(\d{3})\)/) || [])[1] || ''),
+    service: ((rest.match(/\(service:\s*([^)]+)\)/) || [])[1] || '').trim(),
+    acceptance,
+    conditions: acceptanceConditions(acceptance),
+    criteria: criteriaRefs(rest),
+    // De qué otras tareas depende. El orden del BACKLOG alcanzaba mientras hubiera un runner: con dos,
+    // el segundo toma la que sigue mientras el primero construye la de la que depende, y el orden deja
+    // de decir nada.
+    depends: ((rest.match(/\(depende:\s*([^)]+)\)/i) || [])[1] || '')
+      .split(',').map((one) => one.trim()).filter(Boolean),
+    noSplit: noSplitReason(rest),
+  }
+}
+
 function readBacklog(dir) {
   const text = withoutComments(read(path.join(dir, 'BACKLOG.md')))
   const milestones = []
@@ -208,34 +233,28 @@ function readBacklog(dir) {
       continue
     }
     if (/^##\s+/.test(line)) current = null
-    const task = line.match(TASK_LINE)
-    if (!task || !current) continue
-    const rest = task[3]
-    const acceptance = ((rest.match(ACCEPTANCE) || [])[1] || '').trim()
-    current.tasks.push({
-      slug: task[1].trim(), tier: task[2] || '', cast: readCast(rest),
-      epic: ((rest.match(/\(epic:\s*(\d{3})\)/) || [])[1] || ''),
-      service: ((rest.match(/\(service:\s*([^)]+)\)/) || [])[1] || '').trim(),
-      acceptance,
-      conditions: acceptanceConditions(acceptance),
-      criteria: criteriaRefs(rest),
-      noSplit: noSplitReason(rest),
-    })
+    const task = current ? taskFromLine(line) : null
+    if (task) current.tasks.push(task)
   }
   return milestones
 }
 
+// Lo que hay en `done/` y no es una entrada: una tabla de acciones humanas resueltas y la prosa que
+// explica el formato. Se nombran acá porque el lector recorre el directorio entero — una tarea cerrada
+// es un archivo suyo, y cualquier nombre sirve mientras el slug de adentro sea el que manda.
+const NOT_ENTRIES = new Set(['human-actions.md', 'README.md'])
+
 function doneFiles(dir) {
-  const files = [path.join(dir, 'DONE.md')]
-  const archive = path.join(dir, 'done')
   try {
-    files.unshift(...fs.readdirSync(archive).filter((file) => /^epic-\d{3}\.md$/.test(file)).sort()
-      .map((file) => path.join(archive, file)))
-  } catch { /* no archive yet */ }
-  return files
+    return fs.readdirSync(path.join(dir, 'done'))
+      .filter((file) => file.endsWith('.md') && !NOT_ENTRIES.has(file)).sort()
+      .map((file) => path.join(dir, 'done', file))
+  } catch { return [] }
 }
 
-const DONE_FIELDS = 'acept|done|qa|tests|decisions|commit'
+// `fecha` entra al vocabulario porque un campo que no esté acá no corta al anterior: sin nombrarlo, el
+// `done:` de la entrada se lo tragaría entero como parte de su propio texto.
+const DONE_FIELDS = 'acept|fecha|done|qa|tests|decisions|commit'
 
 // Un campo vale hasta el próximo campo, una línea en blanco o el fin de la entrada. Mismo corte que ya
 // se arregló para los criterios y las historias, con el mismo síntoma: el valor es prosa y se envuelve a
@@ -266,7 +285,8 @@ function readDone(dir) {
       entries.push({
         slug: match[1].trim(),
         epic: ((match[2].match(/\(epic:\s*(\d{3})\)/) || [])[1] || ''),
-        acceptance: field('acept'), done: field('done'), qa: field('qa'), tests: field('tests'),
+        acceptance: field('acept'), fecha: field('fecha'),
+        done: field('done'), qa: field('qa'), tests: field('tests'),
         decisions: field('decisions'), commit: field('commit'),
         source: path.relative(dir, file), raw: match[0].trimEnd(),
       })
@@ -302,16 +322,24 @@ const SEPARADORES = /^\|\s*:?-+/
 // afectada —`archive` reescribe `raw`, la línea original, no las celdas—, así que quitarlo no pierde nada.
 const celda = (cell) => cell.trim().replace(/\\\|/g, '|')
 
-function readHumanActions(dir) {
-  const lineas = withoutComments(read(path.join(dir, 'HUMAN_ACTIONS.md'))).split('\n')
-  // En markdown la cabecera es la fila anterior a la de separadores, diga lo que diga su primera celda.
-  // Se marcan todas y no la primera: un archivo con una tabla por sección tiene una cabecera por tabla,
-  // y con `findIndex` la segunda y la tercera vuelven a leerse como datos. Nada más se mueve, porque una
-  // fila de datos nunca está inmediatamente antes de los guiones.
+// Las filas de datos de las tablas de un texto, con las celdas ya normalizadas. Vive acá y no en cada
+// lector porque el escape del pipe tiene que leerse igual en los dos archivos que traen tabla: escrito
+// dos veces, una de las dos copias se pudre sin que nada falle.
+//
+// En markdown la cabecera es la fila anterior a la de separadores, diga lo que diga su primera celda.
+// Se marcan todas y no la primera: un archivo con una tabla por sección tiene una cabecera por tabla,
+// y con `findIndex` la segunda y la tercera vuelven a leerse como datos. Nada más se mueve, porque una
+// fila de datos nunca está inmediatamente antes de los guiones.
+function tableRows(text) {
+  const lineas = text.split('\n')
   const cabeceras = new Set(lineas.map((line, i) => (SEPARADORES.test(line) ? i - 1 : -1)))
-  const rows = lineas
+  return lineas
     .filter((line, i) => /^\|/.test(line) && !SEPARADORES.test(line) && !cabeceras.has(i))
     .map((line) => ({ line, cells: line.split(SEPARADOR).slice(1, -1).map(celda) }))
+}
+
+function readHumanActions(dir) {
+  const rows = tableRows(withoutComments(read(path.join(dir, 'HUMAN_ACTIONS.md'))))
   // El literal queda como resguardo de la tabla escrita sin su fila de separadores: markdown no la
   // renderiza como tabla, y este parser lee sus filas igual.
   return rows.filter(({ cells }) => cells.length >= 4 && !/^tarea$/i.test(cells[0]))
@@ -324,19 +352,47 @@ function readHumanActions(dir) {
     })
 }
 
-function readWip(dir) {
-  const text = read(path.join(dir, 'WIP.md'))
+// El plan de un runner vive en su propio archivo, y el nombre sale de su id. Con una instancia sidecar
+// hay un solo `planning/` por máquina, así que un archivo compartido lo escriben todos los agentes que
+// corren ahí: el segundo pisaba el plan del primero y `context` le entregaba su tarea.
+//
+// El id es una ruta, así que se aplana para poder ser un nombre. Queda largo y legible a propósito —
+// el directorio no viaja por git y sirve para mirar de quién es cada plan cuando algo quedó a medias.
+function wipName(runner) {
+  return String(runner || '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase()
+    || 'sin-runner'
+}
+
+function parseWip(text, runner) {
   if (/^status:\s*IDLE/m.test(text)) return null
   const field = frontmatter(text)
   const task = field('task')
   if (!task) return null
   return {
-    task, phase: field('phase') || '?', service: field('service'),
+    task, runner, phase: field('phase') || '?', service: field('service'),
     complete: (text.match(/^\d+\.\s+\[[xX]\]/gm) || []).length,
     pending: (text.match(/^\d+\.\s+\[\s\]/gm) || []).length,
   }
 }
 
+// El de un runner: el único que le corresponde continuar. El `runner` que devuelve es el nombre
+// aplanado, que es la identidad que hay en disco — devolver el id crudo dejaba a quien compara dos
+// lecturas comparando formas distintas de lo mismo, y no coincidían nunca.
+function readWip(dir, runner) {
+  const name = wipName(runner)
+  return parseWip(read(path.join(dir, 'wip', `${name}.md`)), name)
+}
+
+// Todos los que hay. Lo pregunta `check`, que juzga si cada plan apunta a una tarea que existe, y `tree`,
+// que muestra qué está en vuelo: las dos son preguntas sobre la instancia y no sobre quien pregunta.
+function readWips(dir) {
+  let names = []
+  try { names = fs.readdirSync(path.join(dir, 'wip')) } catch { return [] }
+  return names.filter((name) => name.endsWith('.md')).sort()
+    .map((name) => parseWip(read(path.join(dir, 'wip', name)), name.replace(/\.md$/, '')))
+    .filter(Boolean)
+}
+
 // Un ítem se cuenta cuando empieza con su nombre en negrita, y el nombre existe para poder citarlo
 // —`HUMAN_ACTIONS.md` y las propuestas mensuales se refieren a un ítem por ese slug—. La convención se
 // conserva; lo que no se conserva es el silencio.
@@ -361,7 +417,7 @@ function readInbox(dir) {
 module.exports = {
   EPIC_STATES, HUMAN_ACTION_STATES, LANES, MILESTONE_HEADING, STOP_REASONS,
   TASK_LINE, TASK_LINE_ANY_LANE,
-  read, section, withoutComments, frontmatter, readEpics, readBacklog, readDone, readWip,
-  acceptanceConditions,
+  read, section, withoutComments, frontmatter, readEpics, readBacklog, readDone, readWip, readWips, wipName,
+  acceptanceConditions, tableRows, taskFromLine,
   readInbox, readHumanActions,
 }

package/engine/planning/recurring.js

@@ -0,0 +1,148 @@
+'use strict'
+
+// El contrato de `RECURRING.md`: qué se declaró que vuelve, cuándo vence y qué línea se promueve.
+// No ejecuta ni encola —eso lo decide una persona editando `BACKLOG.md`—; acá se lee el archivo y se
+// calcula una fecha, que es todo lo que la máquina puede aportar sin decidir por nadie.
+//
+// La fecha de hoy entra por parámetro. Preguntarla adentro dejaría cada prueba de vencimiento válida
+// sólo el día que se escribió, y el vencimiento es justamente lo único que este módulo calcula.
+
+const path = require('node:path')
+const P = require('./parser')
+
+const FILE = 'RECURRING.md'
+
+// Vocabulario cerrado, en meses, por la misma razón que el estado de `HUMAN_ACTIONS.md`. `semanal` no
+// está y no es un olvido: el período viaja en el slug de cada vuelta con grano de mes, así que dos
+// vueltas de la misma semana no se distinguirían.
+const CADENCES = { mensual: 1, trimestral: 3, semestral: 6, anual: 12 }
+
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+// `- **qué** AAAA-MM-DD — razón`. El nombre en negrita adelante es la misma convención del INBOX, y por
+// el mismo motivo: es con lo que se cita la fila desde otro lado.
+const POSTPONEMENT = /^-\s+\*\*([^*]+)\*\*\s+(\S+)\s+[—-]\s+(.+)$/
+
+// Suma meses sobre `AAAA-MM-DD` en UTC. El día se recorta al último del mes destino: un ancla escrita
+// el 31 no puede caer en un 31 de febrero, y correrla al 3 de marzo movería la vuelta de mes.
+function addMonths(iso, months) {
+  const [year, month, day] = iso.split('-').map(Number)
+  const target = new Date(Date.UTC(year, month - 1 + months, 1))
+  const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate()
+  target.setUTCDate(Math.min(day, last))
+  return target.toISOString().slice(0, 10)
+}
+
+function daysBetween(from, to) {
+  return Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86400000)
+}
+
+// Las dos listas del archivo, cada una acotada a su sección. Buscarlas en el texto entero haría que una
+// viñeta de la prosa —el archivo explica sus propias columnas con viñetas— entrara como postergación.
+function read(dir) {
+  const text = P.withoutComments(P.read(path.join(dir, FILE)))
+  if (!text.trim()) return { exists: false, rows: [], postponements: [] }
+  const rows = P.tableRows(P.section(text, /Recurrencias/))
+    // El literal, por el mismo motivo que en `readHumanActions`, donde está escrito.
+    .filter(({ cells }) => cells.length >= 4 && !/^qué$/i.test(cells[0]))
+    .map(({ line, cells }) => ({
+      id: cells[0], cadence: cells[1], since: cells[2], task: cells[3], raw: line,
+    }))
+  const postponements = P.section(text, /Postergaciones/).split('\n')
+    .filter((line) => /^-\s/.test(line))
+    .map((line) => {
+      const match = line.match(POSTPONEMENT)
+      return match
+        ? { id: match[1].trim(), date: match[2], reason: match[3].trim(), raw: line }
+        : { id: '', date: '', reason: '', raw: line }
+    })
+  return { exists: true, rows, postponements }
+}
+
+// La línea que se pega en BACKLOG. La celda de la tabla es literalmente la cola de esa línea, así que
+// lo que una persona escribió una vez es lo que se promueve, sin retipear.
+function taskLine(row, period) {
+  return `- [ ] **${row.id}-${period}** — ${row.task}`
+}
+
+function validate({ exists, rows, postponements }) {
+  if (!exists) return []
+  const errors = []
+  const seen = new Set()
+  for (const row of rows) {
+    const at = `${FILE} ${row.id || '(fila sin nombre)'}`
+    if (!ID.test(row.id)) errors.push(`${at}: el identificador va en minúsculas, sin espacios`)
+    else if (seen.has(row.id)) errors.push(`${FILE}: identificador duplicado ${row.id}`)
+    seen.add(row.id)
+    if (!CADENCES[row.cadence]) {
+      errors.push(`${at}: cadencia "${row.cadence}" fuera de ${Object.keys(CADENCES).join(' | ')}`)
+    }
+    if (!DATE.test(row.since)) errors.push(`${at}: Desde debe ser AAAA-MM-DD`)
+    // Se juzga la línea armada y no la celda suelta: lo que se promueve es esa línea, y quien la va a
+    // leer es el mismo lector de BACKLOG. Una celda que pasa acá y una línea que BACKLOG rechaza es el
+    // error que aparece un mes después, con la tarea ya pegada.
+    const task = P.taskFromLine(taskLine(row, '0000-00'))
+    if (!task) errors.push(`${at}: la celda no arma una línea de tarea`)
+    else {
+      if (!task.acceptance) errors.push(`${at}: la tarea no declara _Aceptación: ..._`)
+      if (!task.service) errors.push(`${at}: la tarea no declara (service: <ruta>)`)
+    }
+  }
+  for (const one of postponements) {
+    if (!one.id) {
+      errors.push(`${FILE}: una postergación se escribe "- **qué** AAAA-MM-DD — razón": ${one.raw.trim()}`)
+      continue
+    }
+    if (!DATE.test(one.date)) errors.push(`${FILE}: postergación de ${one.id}: la fecha va en AAAA-MM-DD`)
+    if (!seen.has(one.id)) errors.push(`${FILE}: postergación de ${one.id}, que la tabla no declara`)
+  }
+  return errors
+}
+
+// El último período cerrado, leído de DONE y no de una celda: una fecha que alguien tiene que acordarse
+// de actualizar miente a los tres meses, y la entrada de DONE es además la evidencia de que se hizo.
+function lastPeriod(id, done) {
+  const pattern = new RegExp(`^${id}-(\\d{4}-\\d{2})$`)
+  const periods = done.entries.map((entry) => (entry.slug.match(pattern) || [])[1]).filter(Boolean)
+  return periods.sort().pop() || ''
+}
+
+function status({ rows, postponements, done, today }) {
+  return rows
+    .filter((row) => ID.test(row.id) && CADENCES[row.cadence] && DATE.test(row.since))
+    .map((row) => {
+      const months = CADENCES[row.cadence]
+      const last = lastPeriod(row.id, done)
+      // Cerrada una vuelta, la siguiente se cuenta desde el período que la cerró; sin ninguna, desde el
+      // ancla escrita al declarar la fila. Es lo que hace rodante al vencimiento: saltearse una vuelta
+      // corre la próxima en vez de deber dos.
+      const base = last ? addMonths(`${last}-01`, months) : row.since
+      // Y las postergaciones que cuentan son las escritas después de que terminó el período cerrado:
+      // las anteriores ya las absorbió ese cierre, que es lo que reinicia el contador.
+      const from = last ? addMonths(`${last}-01`, 1) : row.since
+      const postponed = postponements.filter((one) => one.id === row.id && one.date >= from).length
+      const due = addMonths(base, months * postponed)
+      const overdueDays = daysBetween(due, today)
+      return {
+        id: row.id, cadence: row.cadence, task: row.task, last, due, postponed,
+        overdueDays, overdue: overdueDays >= 0,
+      }
+    })
+}
+
+function warnings(state) {
+  const lines = []
+  for (const one of state.filter((candidate) => candidate.overdue)) {
+    const when = one.overdueDays === 0 ? 'vence hoy' : `vencida hace ${one.overdueDays} día(s)`
+    lines.push(`${FILE}: ${one.id} ${when} (${one.due})`)
+  }
+  // Tres seguidas no son un atraso: son una fila que no se va a hacer con la cadencia que declara. El
+  // contador es la alarma, y por eso se cuenta desde el último cierre y no desde siempre.
+  for (const one of state.filter((candidate) => candidate.postponed >= 3)) {
+    lines.push(`${FILE}: ${one.id} postergada ${one.postponed} veces desde el último cierre; `
+      + 'revisá la cadencia o la fila')
+  }
+  return lines
+}
+
+module.exports = { FILE, read, validate, status, warnings, taskLine }

package/engine/planning/state.js

@@ -5,6 +5,7 @@
 // que fija el protocolo. Vivía en el CLI, donde nadie podía ejercitarlo sin lanzar un proceso.
 
 const P = require('./parser')
+const C = require('./claims')
 
 function snapshot(root) {
   const milestones = P.readBacklog(root)
@@ -12,8 +13,9 @@ function snapshot(root) {
     epics: P.readEpics(root),
     milestones,
     done: P.readDone(root),
-    wip: P.readWip(root),
+    wips: P.readWips(root),
     inbox: P.readInbox(root),
+    claims: C.read(root),
     queued: new Set(milestones.flatMap((m) => m.tasks.map((t) => t.slug))),
   }
 }
@@ -31,21 +33,52 @@ function pendingHumanActions(root) {
 // WIP activo primero —es el mutex y manda incluso si tiene una acción humana abierta—, si no la
 // primera tarea no terminada y no bloqueada recorriendo los hitos en su orden: agotado el primero,
 // sigue por el que viene.
-function currentTask({ milestones, done, wip }, blockers = []) {
+//
+// Con equipo se agrega un escalón entre los dos: lo que ya reclamé va antes que lo libre, porque es lo
+// que dije que iba a hacer. Y lo que reclamó otro no se ofrece — sin eso, dos runners preguntando a la
+// vez reciben la misma tarea y ninguno se entera, que es la colisión que no se ve.
+//
+// Quién soy acá es el runner y no la persona: dos agentes en la misma máquina comparten la identidad de
+// git, así que comparar por owner le devolvería a cada uno la tarea del otro como propia.
+function currentTask({ milestones, done, wips = [], claims = [] }, blockers = [], runner = '') {
+  // El plan de otro runner no es asunto de éste: leerlo como propio era lo que le entregaba a un agente
+  // la tarea que otro estaba construyendo, con el WIP ajeno adentro y diciéndole que estaba libre.
+  const wip = wips.find((one) => one.runner === P.wipName(runner)) || null
   const queue = milestones.flatMap((milestone) => milestone.tasks.map((task) => ({ ...task, hito: milestone.slug })))
+  const mine = new Set(claims.filter((one) => runner && one.runner === runner).map((one) => one.slug))
+  const others = new Map(claims.filter((one) => !mine.has(one.slug)).map((one) => [one.slug, one.owner]))
   if (wip) {
     const active = queue.find((task) => task.slug === wip.task)
       || {
         slug: wip.task, hito: '', tier: '', cast: { build: '', review: [] },
         service: wip.service, acceptance: '', epic: '', criteria: [],
       }
-    return { task: active, skipped: [] }
+    return { task: active, claimed: mine.has(wip.task), skipped: [], taken: [], waiting: [] }
   }
   const blocked = new Set(blockers.map((action) => action.task))
-  const pending = queue.filter((task) => !done.set.has(task.slug))
+  const pending = queue.filter((task) => !done.set.has(task.slug) && !blocked.has(task.slug))
+  // Una tarea está lista cuando todo lo que declaró depender ya está en DONE. Mientras no lo esté no se
+  // le ofrece a nadie, y en particular no a otro runner: lo que sigue a una tarea en vuelo es trabajo
+  // del que la tiene, y dárselo a otro produce dos ramas que se van a pisar al integrar.
+  const ready = (task) => (task.depends || []).every((dep) => done.set.has(dep))
+  const claimed = pending.find((task) => mine.has(task.slug))
   return {
-    task: pending.find((task) => !blocked.has(task.slug)) || null,
-    skipped: pending.filter((task) => blocked.has(task.slug)).map((task) => task.slug),
+    task: claimed || pending.find((task) => !others.has(task.slug) && ready(task)) || null,
+    // Que la tarea devuelta ya sea mía o esté libre cambia lo que corresponde hacer con ella, y desde
+    // afuera las dos se ven igual.
+    claimed: Boolean(claimed),
+    skipped: queue.filter((task) => !done.set.has(task.slug) && blocked.has(task.slug))
+      .map((task) => task.slug),
+    taken: pending.filter((task) => others.has(task.slug))
+      .map((task) => ({ slug: task.slug, owner: others.get(task.slug) })),
+    // Lo que espera a otra tarea, con cuál y quién la tiene: la tercera causa por la que una cola puede
+    // no ofrecer nada, y `context` las distingue por la misma razón que distingue las otras dos.
+    // El filtro garantiza que hay dependencias y que al menos una no está cerrada —sin eso la tarea
+    // estaría lista y no acá—, así que buscarla no puede fallar y no lleva defensa.
+    waiting: pending.filter((task) => !others.has(task.slug) && !ready(task)).map((task) => {
+      const dep = task.depends.find((one) => !done.set.has(one))
+      return { slug: task.slug, dep, owner: others.get(dep) || (mine.has(dep) ? 'vos' : '') }
+    }),
   }
 }
 

package/engine/planning/structure.js

@@ -0,0 +1,220 @@
+'use strict'
+
+// Lo que se juzga leyendo el disco: cómo están armados los directorios de planning —roadmap, BACKLOG,
+// reglas y ADR— antes de que alguien componga un estado con ellos.
+//
+// Vive aparte de `contracts.js` porque es la otra mitad de una costura: aquéllas reciben el estado ya
+// leído y se prueban sin tocar disco, éstas abren archivos. Se separaron cuando el archivo cruzó las 500
+// líneas, y lo que decidió el corte fue eso y no el número.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const P = require('./parser')
+
+const EPIC_AUXILIARY_FILES = new Set(['notes.md', 'plan.md', 'research.md', 'spec.md'])
+
+function validateRoadmapStructure(dir) {
+  const roadmap = path.join(dir, 'roadmap')
+  let entries = []
+  try { entries = fs.readdirSync(roadmap, { withFileTypes: true }) } catch { return ['falta roadmap/'] }
+  const errors = []
+  for (const entry of entries) {
+    // Un archivo que se llama como una épica y no cumple el patrón no lo lee nadie: ni `check`, ni
+    // `tree`, ni el runner que busca trabajo. Ignorarlo en silencio es peor que rechazarlo, porque el
+    // planning se reporta válido mientras la épica que alguien escribió no existe para el sistema.
+    if (/^epic-/.test(entry.name) && !/^epic-\d{3}-/.test(entry.name)) {
+      errors.push(
+        `roadmap/${entry.name}: nadie lo lee. Una épica se nombra epic-NNN-<slug>.md, `
+        + 'o un directorio epic-NNN-<slug>/ con spec.md adentro.',
+      )
+      continue
+    }
+    if (!entry.isDirectory() || !/^epic-\d{3}-/.test(entry.name)) continue
+    const epicDir = path.join(roadmap, entry.name)
+    if (!fs.existsSync(path.join(epicDir, 'spec.md'))) {
+      errors.push(`roadmap/${entry.name}: falta spec.md`)
+    }
+    for (const child of fs.readdirSync(epicDir, { withFileTypes: true })) {
+      if (!child.isFile() || !EPIC_AUXILIARY_FILES.has(child.name)) {
+        errors.push(`roadmap/${entry.name}/${child.name}: archivo auxiliar no permitido`)
+      }
+    }
+  }
+  return errors
+}
+
+// El BACKLOG es la única cola, y su lector descarta en silencio lo que no cumple el contrato: una
+// viñeta mal escrita no está en cola, no aparece en `tree` y no la toma nadie, sin que nada falle.
+// Se juzga sólo lo que vive bajo un hito —el encabezado del archivo es prosa— y sólo las viñetas,
+// para no confundir con un error el texto que acompaña a una tarea.
+function validateBacklogStructure(dir) {
+  const text = P.withoutComments(P.read(path.join(dir, 'BACKLOG.md')))
+  const errors = []
+  let milestone = ''
+  for (const line of text.split('\n')) {
+    const heading = line.match(P.MILESTONE_HEADING)
+    if (heading) { milestone = heading[1]; continue }
+    if (/^##\s+Hito\b/.test(line)) {
+      errors.push(`BACKLOG "${line.trim()}": encabezado inválido; se escribe ## Hito <slug> — <Título>, `
+        + 'y sin él las tareas que vienen abajo quedan huérfanas')
+      milestone = ''
+      continue
+    }
+    if (/^##\s+/.test(line)) { milestone = ''; continue }
+    if (!milestone || !/^\s*[-*]\s+\S/.test(line) || P.TASK_LINE.test(line)) continue
+    const lane = line.match(P.TASK_LINE_ANY_LANE)
+    if (lane) {
+      errors.push(`BACKLOG ${lane[1].trim()}: lane "${lane[2]}" no existe; usá ${P.LANES.join(' | ')}, `
+        + 'o dejá la tarea sin clasificar')
+      continue
+    }
+    const at = `BACKLOG hito ${milestone}: no la lee nadie`
+    if (/^-\s+\[[xX]\]/.test(line)) {
+      errors.push(`${at} — ${line.trim().slice(0, 60)}. Una tarea terminada se mueve a DONE.md, no se tilda acá.`)
+      continue
+    }
+    errors.push(`${at} — ${line.trim().slice(0, 60)}. Una tarea se escribe `
+      + '`- [ ] **slug** [lane] — descripción`, con `(→ CN) (epic: NNN)` o `_Aceptación:_` después del guión.')
+  }
+  return errors
+}
+
+// El número de una regla es su identificador, y lo cita todo el sistema: cargos, workflows, plantillas
+// y entradas de DONE. El override se declara escribiendo un archivo con el mismo nombre que el del
+// sistema —ahí redefinir sus números es el punto—; en cualquier otro archivo, reusar un `R` crea una
+// segunda definición que nadie declaró y que ninguna herramienta veía. Las propias se numeran `P`.
+function ruleIds(file) {
+  return [...P.read(file).matchAll(/^##\s+([A-Z]\d+)\s+[—-]/gm)].map((match) => match[1])
+}
+
+// Qué IDs deja de regir un override por nombre: los que definía el archivo del sistema y el propio no
+// redefine. Reemplazar el archivo entero es la función del override y está documentada; lo que no se
+// veía es la consecuencia, porque la advertencia nombraba el par de archivos y no la diferencia. El
+// caso caro es una regla que el motor sigue exigiendo —R17 lo hace—: queda exigida y sin estar escrita
+// en ningún lado, y quien la vea fallar la va a buscar en `rules/`, donde ya no está.
+// Dos secciones de una épica que compiten por el mismo rol. El parser prefiere la exacta, así que
+// resuelve —y en silencio: quien escribió las dos no se entera de que una se ignora entera. La
+// promoción dejó de generarlas cuando lo importado empezó a bajar un nivel; a mano se siguen pudiendo
+// escribir, y ahí el aviso es lo único que lo dice.
+function competingSections(dir) {
+  const roadmap = path.join(dir, 'roadmap')
+  const avisos = []
+  let files = []
+  try { files = fs.readdirSync(roadmap).filter((file) => /^epic-\d{3}-/.test(file)) } catch { return [] }
+  for (const file of files.sort()) {
+    const text = P.read(path.join(roadmap, file))
+    const titles = [...text.matchAll(/^##\s+(.+)$/gm)].map((hit) => hit[1].trim())
+    for (const role of [/Criterios/i, /Historias/i]) {
+      const casan = titles.filter((title) => role.test(title))
+      if (casan.length < 2) continue
+      const exact = new RegExp(`^${role.source}$`, role.flags)
+      const gana = casan.find((title) => exact.test(title)) || casan[0]
+      const ignoradas = casan.filter((title) => title !== gana)
+      avisos.push(`roadmap/${file}: "## ${gana}" convive con "## ${ignoradas.join('", "## ')}"; `
+        + 'sólo se lee la primera y el resto se ignora entero')
+    }
+  }
+  return avisos
+}
+
+function retiredByOverride(dir, name) {
+  const rules = path.join(dir, 'rules')
+  const system = path.join(rules, 'system', name)
+  if (!fs.existsSync(system)) return []
+  const redefined = ruleIds(path.join(rules, name))
+  return ruleIds(system).filter((id) => !redefined.includes(id))
+}
+
+function validateRules(dir) {
+  const rules = path.join(dir, 'rules')
+  const owner = new Map()
+  const errors = []
+  const files = (sub) => {
+    try {
+      return fs.readdirSync(path.join(rules, sub), { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md')
+        .map((entry) => entry.name).sort()
+    } catch { return [] }
+  }
+  const system = new Set(files('system'))
+  for (const name of system) {
+    for (const id of ruleIds(path.join(rules, 'system', name))) {
+      if (owner.has(id)) errors.push(`rules/system/${name}: ${id} ya lo define ${owner.get(id)}`)
+      else owner.set(id, `rules/system/${name}`)
+    }
+  }
+  for (const name of files('')) {
+    // El override se declara por nombre: redefinir los números del archivo que reemplaza es su función.
+    if (system.has(name)) continue
+    for (const id of ruleIds(path.join(rules, name))) {
+      const definedBy = owner.get(id)
+      if (!definedBy) { owner.set(id, `rules/${name}`); continue }
+      errors.push(definedBy.startsWith('rules/system/')
+        ? `rules/${name}: ${id} ya lo define ${definedBy}; una regla propia se numera P1..Pn, `
+          + 'o vive en un archivo con el mismo nombre para declarar el override'
+        : `rules/${name}: ${id} ya lo define ${definedBy}`)
+    }
+  }
+  return errors
+}
+
+// Una decisión que no dice si rige no decide nada, y el molde traía el menú entero en la línea de estado:
+// casi una de cada cinco decisiones escritas con este modelo se publicó con el menú intacto. Presentar
+// las opciones no obliga a elegir; esto sí. Las secciones son las cuatro que se escriben siempre —las
+// alternativas quedan en el molde sin exigirse, porque pedirlas rechazaría a casi todas las que existen—.
+const ADR_STATES = ['Propuesto', 'Aceptado', 'Obsoleto']
+const ADR_SUPERSEDED = /^Reemplazada por \[[^\]]+\]\([^)]+\)(?: \(\d{4}-\d{2}-\d{2}\))?$/
+const ADR_SECTIONS = ['Contexto', 'Decisión', 'Consecuencias', 'Estado de implementación']
+
+function validateAdrFile(at, text) {
+  const errors = []
+  const declared = ((text.match(/^\*\*Estado:\*\*\s*(.+?)\s*$/m) || [])[1] || '').trim()
+  if (!declared) errors.push(`${at}: falta **Estado:**`)
+  else if (declared.includes('|')) errors.push(`${at}: el estado sigue siendo el menú de la plantilla; elegí uno`)
+  else if (!ADR_STATES.includes(declared) && !ADR_SUPERSEDED.test(declared)) {
+    errors.push(`${at}: estado "${declared}" fuera de ${ADR_STATES.join(' | ')} `
+      + '| Reemplazada por [NNN](NNN-slug.md)')
+  }
+  for (const section of ADR_SECTIONS) {
+    if (!new RegExp(`^##\\s+${section}\\s*$`, 'm').test(text)) errors.push(`${at}: falta ## ${section}`)
+  }
+  return errors
+}
+
+// El nombre lleva el id porque de ahí sale la identidad con que se detecta un override, y porque una
+// decisión se cita por número. Sin él, el archivo existe y no lo alcanza ninguna referencia.
+function validateAdr(dir) {
+  const adr = path.join(dir, 'adr')
+  const errors = []
+  const numbers = new Map()
+  const scan = (sub, pattern) => {
+    let entries = []
+    try { entries = fs.readdirSync(path.join(adr, sub), { withFileTypes: true }) } catch { return }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+      if (entry.name === 'README.md' || entry.name === '000-template.md') continue
+      const at = `adr/${sub ? `${sub}/` : ''}${entry.name}`
+      const id = entry.name.match(pattern)
+      if (!id) {
+        errors.push(`${at}: nadie lo lee como decisión. Una ADR se nombra NNN-<slug>.md, `
+          + 'y la del sistema <ID>-NNN-<slug>.md en system/.')
+        continue
+      }
+      if (numbers.has(id[1])) errors.push(`${at}: ${id[1]} ya lo usa ${numbers.get(id[1])}`)
+      else numbers.set(id[1], at)
+      errors.push(...validateAdrFile(at, P.read(path.join(adr, sub, entry.name))))
+    }
+  }
+  scan('', /^(\d{3})-[a-z0-9-]+\.md$/)
+  scan('system', /^([A-Z][A-Z0-9]*-\d{3})-[a-z0-9-]+\.md$/)
+  return errors
+}
+
+module.exports = {
+  validateRoadmapStructure,
+  validateBacklogStructure,
+  competingSections,
+  retiredByOverride,
+  validateRules,
+  validateAdr,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "keywords": [
     "planning",

package/template/.gitattributes

@@ -0,0 +1,19 @@
+# Cómo mergea git lo que el equipo escribe a la vez.
+#
+# `union` concatena los dos lados en vez de marcar conflicto. Vale para un archivo que sólo crece por el
+# final, que es lo que hacen estos dos cuando dos personas registran un bloqueo el mismo día: las dos
+# filas son buenas y van las dos, así que el conflicto no significa nada y hay que resolverlo igual.
+#
+# La evidencia de una tarea cerrada no está acá porque no la necesita: vive en su propio `done/<slug>.md`
+# y nadie escribe el archivo de nadie.
+#
+# El borde: `ops archive human-actions` **quita** filas de la tabla activa al mover las resueltas al
+# histórico, y eso no es crecer por el final. Archivar mientras otro registra un bloqueo puede devolver a
+# la vida una fila resuelta. Es un acto raro y deliberado: se hace con el árbol limpio.
+planning/HUMAN_ACTIONS.md merge=union
+planning/done/human-actions.md merge=union
+
+# INBOX, BACKLOG y RECURRING quedan afuera a propósito. En los tres, quitar una línea es una operación
+# normal y frecuente —promover una idea, sacar una tarea de la cola, retirar una recurrencia— y union
+# la desharía sin que nada lo dijera. Ahí el conflicto es la respuesta correcta: significa que dos
+# personas decidieron sobre lo mismo, y eso se lee.