@ingeniomaps/cauce 0.69.0 → 0.71.0

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.69.0",
+  "version": "0.71.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.

package/template/AGENTS.md

@@ -150,8 +150,9 @@ que hacía falta, apagala después, y que la razón quede escrita donde alguien
 Antes de abrir un archivo de `planning/`, preguntarle al CLI: es determinista, no gasta contexto y no
 muta nada.
 
-- `node tools/ops.js context planning` — gate, mutex de WIP y la tarea que corresponde ahora, con su
-  aceptación y sus criterios. Es la entrada correcta para empezar a trabajar.
+- `node tools/ops.js context planning [--hito <slug>]` — gate, mutex de WIP y la tarea que corresponde
+  ahora, con su aceptación y sus criterios. Es la entrada correcta para empezar a trabajar. Con `--hito`
+  la cola se acota a ese hito, que es como un equipo se reparte trabajo sin coordinarse.
 - `node tools/ops.js tree planning` — panorama de roadmap, backlog, WIP, inbox y done.
 - `node tools/ops.js recurring planning [--promote <qué>]` — qué trabajo recurrente venció y con
   qué línea se promueve. Emite esa línea; escribirla en `BACKLOG.md` es de una persona.
@@ -163,8 +164,49 @@ muta nada.
   nombrada haya corrido —eso depende del runner, y varios no la nombran al pasar— ni reemplaza a leer
   su fuente, que es lo que R9 pide.
 
-Los cinco aceptan `--json`. Leer `BACKLOG.md`, `WIP.md`, `HUMAN_ACTIONS.md` o `RECURRING.md` completos
-sólo cuando haga falta editarlos o cuando el CLI no responda la pregunta.
+Los cinco aceptan `--json`. Leer `BACKLOG.md`, tu `wip/<runner>.md`, `HUMAN_ACTIONS.md` o `RECURRING.md`
+completos sólo cuando haga falta editarlos o cuando el CLI no responda la pregunta.
+
+## Cómo tomar trabajo
+
+Con equipo, la tarea que `context` devuelve puede estar libre o ya ser tuya, y la salida lo dice. Libre
+se toma antes de empezar:
+
+- `node tools/ops.js claim planning <tarea>` — la reserva a tu nombre y escribe `planning/claims/<tarea>.md`.
+- `node tools/ops.js release planning <tarea>` — la devuelve a la cola.
+
+Una tarea que declara `(depende: slug)` no se ofrece ni se puede tomar hasta que eso esté en DONE, y
+`context` la muestra con una línea `WAIT`. No hay que adelantarse: lo que sigue es trabajo de quien tiene
+la tarea de la que depende.
+
+Tomar no es promover: la tarea ya estaba aprobada en `BACKLOG.md` y esto sólo dice quién la hace, así que
+entra en la autonomía del runner. Lo que no entra es tocar el reclamo de otro — ni tomarlo, ni soltarlo—,
+y `context` directamente no ofrece una tarea reclamada.
+
+El reclamo hay que **commitearlo y empujarlo**: sin eso el otro runner lee lo que hay en su copia y la
+reserva no existe para nadie más.
+
+## Con qué runner arrancás
+
+Antes de pedir trabajo hay que saber quién lo tiene. Dos sesiones en la misma máquina resuelven la misma
+identidad de git, así que lo que las distingue es el `CAUCE_RUNNER` de cada una.
+
+`node tools/ops.js runners planning [--json]` dice qué runners tienen una tarea abierta, cuál, desde
+cuándo y si su rama avanzó. Según lo que devuelva:
+
+- **Ninguno** — arrancá con un id propio y no preguntes nada. No hay trabajo que retomar.
+- **Uno o más** — **preguntale a la persona** cuál retoma o si arranca uno nuevo, nombrando la tarea de
+  cada uno, desde cuándo y si avanzó. Retomar el id de un agente que sigue corriendo le saca la tarea, y
+  arrancar uno nuevo cuando había trabajo a medias lo deja huérfano: las dos rompen algo, y por eso la
+  elección no es tuya.
+
+Elegido el id, **exportalo vos** y usalo en cada `ops` de la sesión. **Nunca le pidas a una persona que
+escriba una variable de entorno**: no es el idioma en el que trabaja, y el runner es cómo el toolkit
+distingue dos sesiones, no una decisión de producto. Lo suyo es elegir; la mecánica es tuya.
+
+- `node tools/ops.js worktree planning <tarea>` — prepara el árbol de trabajo de esa tarea y te devuelve
+  la ruta con el `export CAUCE_RUNNER` hecho. No clona nada: `git worktree` comparte el mismo `.git`, y
+  cada árbol queda fijado a su rama, así que ningún agente hace `checkout` sobre el trabajo de otro.
 
 ## Autonomía
 
@@ -200,5 +242,5 @@ publicación tampoco se decide ahí: la decide `allowPush`.
 3. QA valida el comportamiento por el camino real, no por un atajo interno.
 4. La deuda residual va a `planning/INBOX.md`.
 5. El cambio se commitea en el repo del servicio —uno por naturaleza del diff, y una tarea suele
-   tener una sola— y el hash real queda en `DONE.md`.
+   tener una sola— y el hash real queda en la evidencia de la tarea, `planning/done/<slug>.md`.
 6. `node tools/ops.js check planning` queda verde.

package/template/automatization/AGENTS.md

@@ -62,6 +62,6 @@ cambia instalación o materialización, valida `ops init` en un directorio tempo
 
 ## Límites
 
-No edites `planning/BACKLOG.md`, `WIP.md` o `DONE.md` desde hooks o instaladores. No hagas que `ops init` active
+No edites `planning/BACKLOG.md`, `planning/wip/` ni `planning/done/` desde hooks o instaladores. No hagas que `ops init` active
 un runner silenciosamente. No agregues lógica de negocio, nombres de servicios de un proyecto, tokens, rutas
 personales ni modelos concretos a esta capa reusable.

package/template/gitignore

@@ -9,5 +9,14 @@ node_modules/
 # máquina. Committearlo sería historia que nadie lee y un conflicto por commit.
 planning/.verify-log
 
+# El plan de cada runner. Es de la máquina que lo corre —existe para recuperar una ejecución
+# interrumpida, y nadie más puede retomarla— y cambia en cada paso, así que compartirlo es un conflicto
+# por commit a cambio de nada. Lo que el equipo sí necesita saber vive en `planning/claims/`.
+#
+# Se excluyen los planes y no el directorio: git no puede volver a incluir un archivo cuyo directorio
+# está excluido, y el README de ahí adentro sí tiene que viajar.
+planning/wip/*.md
+!planning/wip/README.md
+
 *.tgz
 .DS_Store

package/template/planning/BACKLOG.md

@@ -5,6 +5,10 @@ Solo contiene trabajo aprobado y listo. Las ideas viven en `INBOX.md`.
 La aceptación se escribe en la línea o se hereda del criterio que la tarea cita. El lane y el cast son
 opcionales: sin ellos la tarea está sin clasificar, que es el estado que dispara al clasificador.
 
+`(depende: slug)` declara qué tiene que estar en DONE antes de que esta tarea se pueda tomar. El orden de
+la lista alcanzaba cuando trabajaba un runner; con dos, el segundo toma la que sigue mientras el primero
+construye aquella de la que depende.
+
 Pasando de nueve tareas un hito, o de cinco criterios heredados una tarea, `check` pide decidir (R17):
 o se parte, o lleva `(sin partir: <razón>)` en su línea.
 
@@ -14,4 +18,5 @@ o se parte, o lleva `(sin partir: <razón>)` en su línea.
 - [ ] **slug-de-tarea** [full] — Resultado a construir. _Aceptación: conducta observable._ (service: ruta) (cast: quien-entrega → quien-revisa)
 - [ ] **otro-slug** [lite] — Resultado a construir. (→ C1) (epic: 001) (service: ruta) (cast: quien-entrega → quien-revisa, otro-revisor)
 - [ ] **sin-clasificar** — Resultado a construir. _Aceptación: conducta observable._ (service: ruta)
+- [ ] **la-que-sigue** [lite] — Resultado a construir. _Aceptación: conducta observable._ (service: ruta) (depende: slug-de-tarea)
 -->

package/template/planning/FLOW.md

@@ -5,7 +5,7 @@ INBOX ──promoción humana──▶ roadmap ──historias listas──▶ B
   ▲                                                           │
   │                                                        Pick/Plan
   │                                                           ▼
-  │      done/ ◀── archive ◀── DONE ◀── Verify/QA ◀────────── WIP
+  │        done/<tarea>.md ◀── evidencia ◀── Verify/QA ◀───── WIP
   │                                                           │
   └───────────── deuda adyacente ─────────────────────────────┤
                                                               │

package/template/planning/PROTOCOL.md

@@ -9,9 +9,12 @@ invariantes.
   `(service: ruta)`.
 - Hito: `## Hito slug — Título`.
 - Tarea: `- [ ] **slug** [express|directo|lite|full] — descripción. _Aceptación: observable._ (service: ruta) (cast: quien-entrega → quien-revisa, otro)`;
-  puede heredar aceptación usando `(→ CN) (epic: NNN)`. Lane y cast son opcionales: sin ellos la tarea
-  está sin clasificar, que es un estado y no un error.
-- DONE: entrada `[x]` con `acept:`, `done:`, `qa:`, `tests:` y `commit:`. `tests:` enlaza cada criterio
+  puede heredar aceptación usando `(→ CN) (epic: NNN)` y declarar `(depende: slug, otro)`. Lane y cast son
+  opcionales: sin ellos la tarea está sin clasificar, que es un estado y no un error. Una tarea con
+  dependencias no se ofrece ni se toma hasta que todas estén en DONE.
+- DONE: un archivo por tarea cerrada, `done/<slug>.md`, con su entrada `[x]` y los campos `acept:`,
+  `fecha:` en AAAA-MM-DD, `done:`, `qa:`, `tests:` y `commit:`. La fecha es la del cierre, y es lo que
+  ordena una evidencia que ya no depende de su posición dentro de un archivo. `tests:` enlaza cada criterio
   mediante `CN → prueba`; usa `A → prueba` cuando no hay épica o `n/a — razón` si no existe una
   superficie ejecutable. `decisions:` es opcional y, si aparece, cita `[fuente: ...]` o
   `[supuesto: ...]`. `commit:` apunta a `<sha> <asunto>`, o a `n/a — razón` cuando la tarea no
@@ -25,12 +28,18 @@ invariantes.
   cola de su línea de BACKLOG. Vencer no bloquea: cada vuelta se promueve con el período en el slug
   —`<qué>-AAAA-MM`— y esa promoción la escribe una persona. Postergar se registra bajo
   `## Postergaciones` con `- **qué** AAAA-MM-DD — razón`.
-- WIP activo: frontmatter y checklist; inactivo: `status: IDLE`.
+- Reclamo: `claims/<tarea>.md` con frontmatter `task/owner/runner/started/service`; el nombre del
+  archivo es el slug que reserva, y por eso un `task` que diga otra cosa es un error. `owner` dice a
+  quién preguntarle y `runner` decide de quién es: con varios agentes en una máquina la persona es
+  la misma y el árbol de trabajo no.
+- WIP activo: frontmatter y checklist en `wip/<runner>.md`; inactivo cuando el archivo no está. Es
+  local y no viaja por git: existe para recuperar la sesión de quien lo escribió, y es uno por runner
+  porque una instancia sidecar la comparten todos los agentes de esa máquina.
 
 ## Gates de arranque
 
 1. Si existe `AWAITING_REVIEW.md`, parar y mostrar la acción que contiene.
-2. Si WIP está activo y puede pertenecer a otro runner, parar: es el mutex.
+2. Si tu WIP está activo, la tarea es ésa: es el mutex del runner, y sólo se lee el propio.
 3. Si WIP está activo tras una interrupción confirmada, verificar los pasos `[x]` en disco y continuar
    desde el primer `[ ]`; no replanear.
 4. Si WIP apunta a una tarea ya en DONE y fuera de BACKLOG, reparar el cierre dejando WIP en IDLE.
@@ -38,7 +47,8 @@ invariantes.
 ## Máquina por tarea
 
 1. Triage: inspeccionar estado y cambios existentes.
-2. Pick: primera tarea no bloqueada del primer hito.
+2. Pick: primera tarea no bloqueada ni reclamada por otro runner, recorriendo los hitos en orden;
+   reclamarla antes de empezar y empujar ese reclamo, que sin empujar no reserva nada.
 3. Classify: si la tarea no declara lane y cast, decidirlos y escribirlos en su línea.
 4. Ready: exigir aceptación concreta y decisiones resueltas.
 5. Decompose: dividir trabajo mayor a `maxTaskHours` o con más de cinco condiciones de aceptación.
@@ -49,7 +59,8 @@ invariantes.
 10. Verify: ejecutar los gates declarados por el servicio y registrar exit codes.
 11. QA: probar la aceptación por el camino que usa un consumidor real.
 12. Commit: stage explícito y commits verificables, uno por naturaleza del diff.
-13. Done: mover la tarea, registrar evidencia, limpiar WIP y cerrar/archivar la épica si corresponde.
+13. Done: sacar la tarea de la cola, escribir su evidencia en `done/<slug>.md`, limpiar WIP, soltar
+    el reclamo y cerrar la épica si no le queda ninguna historia abierta.
 14. Cierre: check verde, deuda residual al INBOX y checkpoint entre hitos.
 
 ## Lanes
@@ -70,10 +81,25 @@ El lane reduce ceremonia, nunca seguridad, aceptación ni evidencia: Verify y el
 cuatro. Lo que decide el carril es la superficie del cambio y no su tamaño en líneas — un `if` en el
 chequeo de permisos es `full`, y un componente entero de presentación puede ser `directo`.
 
+Escribir la línea es también contrastarla. Declara cuatro cosas —qué hace, en qué carril, quién entrega y
+revisa, con qué se comprueba— y las cuatro salen de la misma mano en el mismo acto, así que nada las cruza
+después. Releerlas no encuentra el hueco: una aceptación incompleta se lee perfecta, porque todo lo que
+dice es cierto.
+
+Antes de dar la tarea por escrita se recorre su descripción frase por frase y se contesta, por cada cosa
+que promete, cuál condición de aceptación la comprueba; se lee el carril contra la superficie que toca y
+no contra su tamaño; y se comprueba que el cast entregue a quien construye. Lo que quede sin condición se
+agrega o se declara fuera de alcance en la línea.
+
+Es el único momento en que las cuatro se pueden mirar juntas, y por eso la pasada vive acá y no en una
+fase: después el carril ya decide cuáles corren, y la que revisaría es una de las que ese carril puede
+saltar. Una tarea mal marcada `express` es justamente la que se salta la fase donde alguien lo notaría.
+
 ## Invariantes
 
 1. Una tarea tiene un dueño de estado: roadmap → BACKLOG → overlay WIP → DONE.
-2. Un solo runner a la vez; WIP activo es mutex — `business-rules/system/BR-OPS-001`.
+2. Un runner lleva una tarea a la vez —WIP, que es local: `business-rules/system/BR-OPS-001`— y una
+   tarea la lleva un runner —el reclamo, que es compartido: `business-rules/system/BR-OPS-005`—.
 3. INBOX nunca se ejecuta automáticamente — `business-rules/system/BR-OPS-002`.
 4. No declarar éxito sin comandos, resultados y exit codes reales — `business-rules/system/BR-OPS-004`.
 5. No inventar credenciales ni decisiones; registrar HUMAN_ACTIONS.

package/template/planning/README.md

@@ -7,8 +7,8 @@ Se lee y se escribe en cada tarea.
 | Pieza | Responsabilidad |
 |---|---|
 | `BACKLOG.md` | Única cola de tareas promovidas y listas. |
-| `WIP.md` | Única tarea en vuelo; recuperación y mutex. |
-| `DONE.md` | Evidencia activa de tareas terminadas. |
+| `wip/` | El plan en vuelo de cada runner; recuperación y mutex por runner. No viaja por git. |
+| `claims/` | Qué tarea tomó cada quien; un archivo por tarea. |
 | `HUMAN_ACTIONS.md` | Acciones externas que requieren una persona. |
 | `AWAITING_REVIEW.md` | Gate efímero; mientras existe no inicia trabajo. |
 
@@ -32,7 +32,7 @@ Evidencia que no se reescribe.
 
 | Pieza | Responsabilidad |
 |---|---|
-| `done/` | Historial inmutable: una épica cerrada por archivo, más las acciones humanas resueltas. |
+| `done/` | Evidencia de lo terminado: una tarea cerrada por archivo, más las acciones humanas resueltas. |
 | `reports/` | Informes de recorridos de equipo. |
 
 El protocolo exacto está en `PROTOCOL.md`, la explicación visual en `FLOW.md` y los principios que

package/template/planning/RECURRING.md

@@ -26,7 +26,7 @@ vencimiento se calcula cuando alguien corre el CLI. Promover sigue siendo un act
 Se cuenta desde la última vez que se cerró, no desde un día fijo del calendario: una recurrencia
 atrasada no debe tres vueltas, debe una, la que no se hizo.
 
-La fecha de ese último cierre **no se escribe acá**. Sale de `DONE.md` — la entrada más nueva cuyo slug
+La fecha de ese último cierre **no se escribe acá**. Sale de `done/` — la entrada más nueva cuyo slug
 sea `<qué>-AAAA-MM`—, que es la evidencia de que efectivamente se hizo y no la afirmación de que se
 hizo. Una celda que alguien tiene que acordarse de actualizar miente a los tres meses, y el estado no se
 copia para representar progreso.

package/template/planning/adr/system/OPS-001-planificacion-como-fuente-de-verdad.md

@@ -13,8 +13,9 @@ en conversaciones, tickets y memoria del runner hace imposible saber qué está
 ## Decisión
 
 **La instancia usa `planning/` como fuente de verdad operativa, legible y validable.** `INBOX.md` recibe ideas,
-el roadmap define resultados, `BACKLOG.md` contiene trabajo promovido, `WIP.md` conserva una única ejecución y
-`DONE.md` registra evidencia. El protocolo define las transiciones permitidas.
+el roadmap define resultados, `BACKLOG.md` contiene trabajo promovido, `wip/<runner>.md` conserva la ejecución de cada runner y
+y `done/<slug>.md` registra la evidencia de cada tarea cerrada, un archivo por tarea. El protocolo
+define las transiciones permitidas.
 
 ## Alternativas consideradas
 

package/template/planning/business-rules/system/BR-OPS-001-una-sola-tarea-activa.md

@@ -1,8 +1,9 @@
 # Una sola tarea activa
 
-> **Dominio:** planning | **Estado:** vigente | **Actualizado:** 2026-08-14
+> **Dominio:** planning | **Estado:** vigente | **Actualizado:** 2026-09-07
 
-WIP protege la exclusión mutua y permite recuperar una ejecución interrumpida.
+WIP protege la exclusión mutua dentro de un runner y permite recuperar una ejecución interrumpida.
+Que dos runners no tomen la misma tarea es otra cosa, y la sostiene `BR-OPS-005-una-tarea-un-runner.md`.
 [fuente: ../../adr/system/OPS-001-planificacion-como-fuente-de-verdad.md]
 
 Elabora el invariante 2 de `../../PROTOCOL.md`, que lo enuncia en una línea: acá viven sus bordes
@@ -12,7 +13,7 @@ y su evidencia. Cambiar una sin la otra las separa.
 
 | ID | Regla | Condición y resultado |
 |---|---|---|
-| BR-OPS-001 | WIP es mutex | Si WIP está activo, ningún runner toma otra tarea hasta continuarlo o resolverlo. |
+| BR-OPS-001 | WIP es mutex | Si WIP está activo, ese runner no toma otra tarea hasta continuarlo o resolverlo. |
 
 ## Por qué existe cada regla
 
@@ -24,7 +25,8 @@ y su evidencia. Cambiar una sin la otra las separa.
 |---|---|
 | Sesión interrumpida | Se verifican pasos persistidos y se continúa la misma tarea. |
 | Tarea ya cerrada | Se repara el cierre y WIP vuelve a `IDLE`; no se ejecuta otra vez. |
-| Dueño incierto | Se detiene y solicita revisión; no se asume abandono. |
+| WIP ausente | Se lee como IDLE. El archivo es local y un clon nuevo no lo trae; eso no es un error. |
+| Tarea de otro runner | No la ve: el WIP ajeno no viaja. Lo que la reserva es su reclamo (BR-OPS-005). |
 
 ## Evidencia
 
@@ -36,3 +38,4 @@ y su evidencia. Cambiar una sin la otra las separa.
 | Fecha | Cambio | Origen |
 |---|---|---|
 | 2026-08-14 | Creación | OPS-001 y `PROTOCOL.md`. |
+| 2026-09-07 | El mutex se acota al runner; el WIP pasa a ser local | Trabajo en equipo: `../../delivery/teamwork.md`. |

package/template/planning/business-rules/system/BR-OPS-005-una-tarea-un-runner.md

@@ -0,0 +1,44 @@
+# Una tarea, un runner
+
+> **Dominio:** planning | **Estado:** vigente | **Actualizado:** 2026-09-07
+
+El reclamo protege la exclusión mutua entre runners y hace visible quién sostiene cada tarea.
+[fuente: ../../adr/system/OPS-001-planificacion-como-fuente-de-verdad.md]
+
+Es la contracara de `BR-OPS-001-una-sola-tarea-activa.md`, y las dos juntas son el invariante 2 de
+`../../PROTOCOL.md`. Se parecen y no son la misma: aquélla impide que un runner lleve dos tareas y vive
+en su `wip/<runner>.md`, que es local; ésta impide que dos runners lleven la misma y vive en `claims/`, que es
+compartido. Con una sola, un equipo trabaja una tarea por vez o duplica trabajo sin enterarse.
+
+## Reglas
+
+| ID | Regla | Condición y resultado |
+|---|---|---|
+| BR-OPS-005 | El reclamo reserva | Una tarea reclamada no se ofrece a otro runner ni se toma hasta que su reclamo se suelte. |
+
+## Por qué existe cada regla
+
+- **BR-OPS-005:** sin reserva, dos runners que preguntan a la vez reciben la misma tarea y ninguno lo
+  nota: el trabajo se duplica y el conflicto aparece recién al mergear, cuando ya se pagó dos veces.
+
+## Casos borde
+
+| Caso | Comportamiento esperado |
+|---|---|
+| Reclamo propio | Se continúa esa tarea; es lo que el runner declaró que iba a hacer. |
+| Reclamo de otro | La tarea no se ofrece; se toma la siguiente libre. |
+| Reclamo sin empujar | No protege a nadie: el otro runner lee lo que hay en su copia. |
+| Reclamo abandonado | Se avisa por antigüedad; soltarlo es un acto humano, no un comando. |
+| Tarea ya en DONE | El reclamo sobra y se avisa; la evidencia no depende de él. |
+
+## Evidencia
+
+- `ops context` no devuelve una tarea con reclamo ajeno y nombra quién la tiene.
+- `ops check` rechaza un reclamo cuya tarea no existe en BACKLOG ni DONE.
+- `ops claim` se niega a pisar el reclamo de otro.
+
+## Historial
+
+| Fecha | Cambio | Origen |
+|---|---|---|
+| 2026-09-07 | Creación | Trabajo en equipo: `../../delivery/teamwork.md`. |