@ingeniomaps/cauce 0.69.0 → 0.70.0

package/engine/planning/adoption.js

@@ -96,7 +96,7 @@ function report({ done, epics = [], adopted = [] }) {
   for (const slug of slugs) {
     const entry = done.entries.find((candidate) => candidate.slug === slug)
     if (!entry) {
-      warnings.push(`${BASELINE}: ${slug} no está en DONE.md; sacalo de la lista`)
+      warnings.push(`${BASELINE}: ${slug} no está en done/; sacalo de la lista`)
     } else if (!PC.doneEntryErrors(entry, epics).length) {
       warnings.push(`${BASELINE}: ${slug} ya cumple el contrato; retiralo poniéndole \`#~\` delante`)
     }

package/engine/planning/claims.js

@@ -0,0 +1,153 @@
+'use strict'
+
+// Quién tomó qué. Un archivo por tarea reclamada: crearlo es reclamar, borrarlo es soltar.
+//
+// El nombre del archivo es el slug de la tarea, y de ahí sale la única propiedad que importa: dos
+// personas en tareas distintas no tocan el mismo archivo nunca, y dos que reclaman la misma chocan en
+// git — que es exactamente donde el choque significa algo y donde conviene verlo.
+//
+// El plan de la ejecución no vive acá. Eso es `wip/<runner>.md`, que es local y cambia en cada paso; acá va lo
+// poco que el resto del equipo necesita saber, que cambia dos veces por tarea. Son dos responsabilidades
+// distintas y por eso son dos archivos: el reclamo evita que dos runners tomen la misma tarea, y el WIP
+// evita que un runner lleve dos.
+
+const fs = require('node:fs')
+const { spawnSync } = require('node:child_process')
+const path = require('node:path')
+const P = require('./parser')
+
+const DIR = 'claims'
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+// Tres días **sin ninguna señal de avance**, que no es lo mismo que tres días desde que se tomó. El
+// tiempo transcurrido solo no distingue una tarea larga de una abandonada, y equivocarse en esa
+// distinción es caro en los dos sentidos: apurar a alguien que está trabajando, o dejar bloqueada para
+// siempre la tarea de quien se fue.
+//
+// Lo que sí distingue es si la rama de la tarea se movió. Con esa señal, tres días sin un solo commit no
+// es una tarea larga: es una que se detuvo, y el aviso manda a mirar y no a soltar.
+const STALE_DAYS = 3
+
+// Quién soy. Sale de la identidad de git porque ya está configurada, es por máquina y es la que va a
+// terminar en el commit igual: pedir una segunda identidad sólo para esto sería un dato más que puede
+// quedar desincronizado. `CAUCE_OWNER` la pisa donde no la haya —un contenedor de CI, por ejemplo—.
+//
+// Sin identidad no se puede reclamar, y eso es correcto: un reclamo anónimo no le dice a nadie a quién
+// preguntarle.
+function owner(root) {
+  if (process.env.CAUCE_OWNER) return process.env.CAUCE_OWNER.trim()
+  const result = spawnSync('git', ['config', 'user.email'], { cwd: root, encoding: 'utf8' })
+  return result.status === 0 ? (result.stdout || '').trim() : ''
+}
+
+// Qué runner soy, que no es lo mismo que quién soy. En una máquina con varios agentes la identidad de
+// git es la misma para todos —`git config user.email` no distingue una sesión de otra—, así que si lo
+// que decide «esto es mío» fuera el owner, el segundo agente tomaría por propia la tarea del primero y
+// los dos construirían lo mismo. La unidad es el árbol de trabajo: uno por agente.
+//
+// `CAUCE_RUNNER` es la vía explícita y la que deja `ops worktree`. Sin ella se deduce del árbol donde
+// corre el proceso, que acierta cuando el agente invoca desde el suyo y falla —devolviendo el mismo id
+// para todos— cuando invoca desde una instancia sidecar compartida. Esa falla no queda en silencio:
+// `claim` se niega a darle una segunda tarea a un runner que ya tiene una, y ese es el mensaje que
+// manda a poner la variable.
+function runner() {
+  if (process.env.CAUCE_RUNNER) return process.env.CAUCE_RUNNER.trim()
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' })
+  return result.status === 0 ? (result.stdout || '').trim() : process.cwd()
+}
+
+// La rama donde vive el trabajo de una tarea. La escriben `worktree` al crearla y `check` al buscar si
+// se movió, y son la misma o el segundo mira una rama que nadie usa.
+const branchOf = (slug) => `task/${slug}`
+
+function file(root, slug) {
+  return path.join(root, DIR, `${slug}.md`)
+}
+
+function read(root) {
+  let names = []
+  try { names = fs.readdirSync(path.join(root, DIR)) } catch { return [] }
+  return names.filter((name) => name.endsWith('.md') && name !== 'README.md').sort()
+    .map((name) => {
+      const field = P.frontmatter(P.read(path.join(root, DIR, name)))
+      return {
+        slug: name.replace(/\.md$/, ''),
+        task: field('task'),
+        owner: field('owner'),
+        runner: field('runner'),
+        started: field('started'),
+        service: field('service'),
+        at: `${DIR}/${name}`,
+      }
+    })
+}
+
+// El cuerpo de un reclamo. Es corto a propósito: todo lo que crezca acá vuelve a viajar por git en cada
+// cambio, que es de lo que este archivo vino a separarse.
+function content({ task, owner, runner: from, started, service }) {
+  return `---\ntask: ${task}\nowner: ${owner}\nrunner: ${from}\nstarted: ${started}\n`
+    + `service: ${service || ''}\n---\n\nTomada. El plan vive en el \`wip/\` de quien la tomó.\n`
+}
+
+function validate({ claims, milestones, done }) {
+  const errors = []
+  const queued = new Set(milestones.flatMap((milestone) => milestone.tasks).map((task) => task.slug))
+  for (const claim of claims) {
+    const at = `${claim.at}`
+    // El nombre del archivo es lo que hace única la reserva, así que un frontmatter que dice otra cosa
+    // reclama una tarea y bloquea otra. Es la única forma en que este contrato puede mentir.
+    if (claim.task !== claim.slug) {
+      errors.push(`${at}: declara task "${claim.task}" y el archivo reserva ${claim.slug}`)
+    }
+    if (!claim.owner) errors.push(`${at}: falta owner`)
+    if (!claim.runner) errors.push(`${at}: falta runner`)
+    if (!DATE.test(claim.started)) errors.push(`${at}: started debe ser AAAA-MM-DD`)
+    if (!queued.has(claim.slug) && !done.set.has(claim.slug)) {
+      errors.push(`${at}: ${claim.slug} no existe en BACKLOG ni DONE`)
+    }
+  }
+  return errors
+}
+
+const days = (from, to) => Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`))
+  / 86400000)
+
+// `activity` mapea el slug de una tarea a la fecha del último commit de su rama. Llega de afuera porque
+// resolverlo exige git y la configuración del proyecto, y este módulo se prueba sin ninguna de las dos.
+// Vacío es un estado legítimo —una tarea recién tomada no tiene rama— y entonces la única señal que
+// queda es cuándo se tomó.
+function warnings({ claims, done, today, activity = new Map() }) {
+  const lines = []
+  for (const claim of claims) {
+    if (done.set.has(claim.slug)) {
+      lines.push(`${claim.at}: ${claim.slug} ya está en DONE; soltala con \`ops release\``)
+      continue
+    }
+    if (!DATE.test(claim.started)) continue
+    const commit = activity.get(claim.slug) || ''
+    const ultima = commit && commit > claim.started ? commit : claim.started
+    const quieta = days(ultima, today)
+    if (quieta > STALE_DAYS) {
+      const senal = commit
+        ? `último commit hace ${days(commit, today)} días`
+        : 'la rama de la tarea no tiene commits'
+      lines.push(`${claim.at}: ${claim.slug} sin avanzar hace ${quieta} días `
+        + `(${claim.owner}, tomada hace ${days(claim.started, today)}; ${senal}); mirá si sigue viva`)
+    }
+  }
+  // Dos tareas del mismo servicio pueden tocar los mismos archivos, y eso no se puede saber antes de
+  // hacerlas. Lo único que se puede es decirlo a tiempo de que hablen, así que avisa y nunca frena:
+  // frenar serializaría a un equipo entero sobre un servicio, que es peor que la colisión que evita.
+  const byService = new Map()
+  for (const claim of claims.filter((one) => one.service && !done.set.has(one.slug))) {
+    byService.set(claim.service, [...(byService.get(claim.service) || []), claim])
+  }
+  for (const [service, group] of byService) {
+    if (group.length < 2) continue
+    lines.push(`${group.length} tareas tomadas sobre ${service} `
+      + `(${group.map((one) => `${one.slug} · ${one.owner}`).join('; ')}); pueden tocar los mismos archivos`)
+  }
+  return lines
+}
+
+module.exports = { DIR, STALE_DAYS, owner, runner, branchOf, file, read, content, validate, warnings }

package/engine/planning/contracts.js

@@ -8,7 +8,6 @@ const { PLACEHOLDERS } = require('../core/onboarding')
 const TEST_TRACE = /^(?:n\/a\s*[—-]\s*.+|(?:A|C\d+)\s*(?:→|->)\s*\S.+)$/i
 const DECISION_TRACE = /\[(?:fuente|supuesto):\s*[^\]]+\]/i
 const COMMIT_TRACE = /^(?:n\/a\s*[—-]\s*.+|[0-9a-f]{7,40}\s+\S.*)$/i
-const EPIC_AUXILIARY_FILES = new Set(['notes.md', 'plan.md', 'research.md', 'spec.md'])
 
 function validTestTrace(value) {
   return String(value || '').split(/\s*;\s*/).filter(Boolean)
@@ -75,6 +74,9 @@ function doneEntryErrors(entry, epics = []) {
   const at = `${entry.source} ${entry.slug}`
   const errors = []
   if (!entry.acceptance) errors.push(`${at}: falta acept:`)
+  // La fecha de cierre. Mientras las entradas vivían en un archivo, el orden lo daba la posición; con un
+  // archivo por tarea no hay posición, y sin fecha no hay forma de saber cuál se cerró antes.
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.fecha)) errors.push(`${at}: falta fecha: AAAA-MM-DD`)
   if (!entry.done) errors.push(`${at}: falta done:`)
   if (!entry.qa) errors.push(`${at}: falta qa:`)
   if (!entry.commit) errors.push(`${at}: falta commit:`)
@@ -117,201 +119,41 @@ function validateEpic(epic, done = new Set()) {
   return errors
 }
 
-function validateRoadmapStructure(dir) {
-  const roadmap = path.join(dir, 'roadmap')
-  let entries = []
-  try { entries = fs.readdirSync(roadmap, { withFileTypes: true }) } catch { return ['falta roadmap/'] }
+// Las dependencias declaradas, contra lo que existe y contra sí mismas. Dos errores distintos y los dos
+// dejan tareas que no se le ofrecen a nadie: una que depende de algo que no existe no está lista nunca, y
+// un ciclo se traba entero. Las dos se ven como una cola que no avanza y sin causa visible.
+function dependencyErrors(milestones, done) {
   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`)
+  const tasks = milestones.flatMap((milestone) => milestone.tasks)
+  const queued = new Map(tasks.map((task) => [task.slug, task.depends || []]))
+  for (const task of tasks) {
+    for (const dep of task.depends || []) {
+      if (dep === task.slug) errors.push(`BACKLOG ${task.slug}: depende de sí misma`)
+      else if (!queued.has(dep) && !done.set.has(dep)) {
+        errors.push(`BACKLOG ${task.slug}: depende de ${dep}, que no existe en BACKLOG ni DONE`)
       }
     }
   }
-  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
+  // Recorrido en profundidad con el camino a cuestas: al reencontrar un slug que sigue en el camino,
+  // ese camino **es** el ciclo, y nombrarlo entero es lo que lo hace reparable — decir sólo que hay uno
+  // deja el trabajo de encontrarlo del lado de quien lee.
+  const estado = new Map()
+  const visitar = (slug, camino) => {
+    if (estado.get(slug) === 'listo') return
+    const desde = camino.indexOf(slug)
+    if (desde >= 0) {
+      const ciclo = [...camino.slice(desde), slug]
+      errors.push(`BACKLOG: ciclo de dependencias ${ciclo.join(' → ')}`)
+      return
     }
-    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')
+    for (const dep of queued.get(slug) || []) {
+      // La que se depende a sí misma ya tiene su error, más claro que un ciclo de un solo paso.
+      if (dep !== slug && queued.has(dep)) visitar(dep, [...camino, slug])
     }
+    estado.set(slug, 'listo')
   }
-  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
+  for (const slug of queued.keys()) visitar(slug, [])
+  return [...new Set(errors)]
 }
 
 // Todo lo que se juzga sobre el estado ya leído: épicas, hitos, tareas, WIP, evidencia y acciones
@@ -319,7 +161,7 @@ function validateAdr(dir) {
 // `validateDoneEntry`, `validateRules`— y estaba creciendo del otro lado sólo porque ahí era más
 // rápido escribirla. No lee nada: recibe el estado, así que se prueba sin tocar disco.
 function validateState({
-  epics, milestones, done, wip, roles = new Set(), humanActions = [], adopted = new Set(),
+  epics, milestones, done, wips = [], roles = new Set(), humanActions = [], adopted = new Set(),
 }) {
   const errors = []
   const epicNums = new Set()
@@ -399,15 +241,20 @@ function validateState({
     }
   }
 
-  if (wip && !backlogSlugs.has(wip.task) && !done.set.has(wip.task)) {
-    errors.push(`WIP ${wip.task}: no existe en BACKLOG ni DONE`)
-  }
+  errors.push(...dependencyErrors(milestones, done))
+
+  for (const wip of wips) {
+    const at = `wip/${wip.runner}.md`
+    if (!backlogSlugs.has(wip.task) && !done.set.has(wip.task)) {
+      errors.push(`${at}: ${wip.task} no existe en BACKLOG ni DONE`)
+    }
   // El WIP es el punto de retorno tras una interrupción, y el protocolo manda seguir desde el primer
   // paso sin tildar. Un plan que el motor no puede contar se lee como un plan terminado, así que la
   // recuperación se queda sin de dónde retomar justo cuando es lo único que quedó del trabajo.
-  if (wip && !wip.complete && !wip.pending) {
-    errors.push(`WIP ${wip.task}: el plan no tiene pasos que el motor pueda contar; `
-      + 'se escriben `1. [ ] paso`')
+    if (!wip.complete && !wip.pending) {
+      errors.push(`${at}: el plan de ${wip.task} no tiene pasos que el motor pueda contar; `
+        + 'se escriben `1. [ ] paso`')
+    }
   }
   for (const row of humanActions) {
     if (!row.valid) {
@@ -444,15 +291,9 @@ function validateState({
 module.exports = {
   validateState,
   doneEntryErrors,
-  validateAdr,
-  validateRules,
-  retiredByOverride,
-  competingSections,
-  validateBacklogStructure,
   validCommitTrace,
   validDecisionTrace,
   validTestTrace,
   validateDoneEntry,
   validateEpic,
-  validateRoadmapStructure,
 }

package/engine/planning/parser.js

@@ -209,6 +209,11 @@ function taskFromLine(line) {
     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),
   }
 }
@@ -234,17 +239,22 @@ function readBacklog(dir) {
   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
@@ -275,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(),
       })
@@ -341,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.
@@ -378,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,
+  read, section, withoutComments, frontmatter, readEpics, readBacklog, readDone, readWip, readWips, wipName,
   acceptanceConditions, tableRows, taskFromLine,
   readInbox, readHumanActions,
 }

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' : '') }
+    }),
   }
 }