@ingeniomaps/cauce 0.68.0 → 0.70.0

package/CHANGELOG.md

@@ -14,6 +14,165 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
 diseño — eso vive en el commit y en el código.
 
+## [0.70.0] - 2026-09-08
+
+### Agregado
+
+- **`planning/claims/`: quién tomó qué, para que dos runners no construyan lo mismo.** Un archivo por tarea
+  tomada, con el slug de la tarea como nombre: `ops claim planning <tarea>` lo crea y `ops release` lo borra.
+  `ops context` deja de ofrecer una tarea con reclamo ajeno —antes le entregaba la misma a los dos y ninguno
+  se enteraba—, nombra quién la tiene y devuelve antes lo que vos reclamaste que lo que está libre.
+
+  Es un archivo por tarea y no uno por persona a propósito: así dos personas en tareas distintas no tocan
+  nunca el mismo archivo, y dos que toman la misma chocan en git, que es donde el choque significa algo.
+  `check` rechaza el reclamo que nombra una tarea que no existe, avisa a los tres días de tomada y avisa
+  cuando hay dos reclamos sobre el mismo `service:` — avisa y no frena, porque frenar serializaría a un
+  equipo entero sobre un servicio.
+
+  El reclamo distingue `owner` —la persona, a quién preguntarle— de `runner` —el agente que la hace—, y
+  lo segundo es lo que decide de quién es una tarea. Con varios agentes en una máquina la persona es la
+  misma y el árbol de trabajo no: sin esa distinción, el segundo agente tomaría por propia la tarea del
+  primero. Se crea con exclusión —el archivo se abre en modo exclusivo, así que dos reclamos simultáneos
+  no se pisan— y un runner lleva una tarea a la vez.
+
+  **Lo que te pide algo**: 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—. Y si corrés varios agentes en la misma
+  máquina, cada uno exporta `CAUCE_RUNNER` con un valor propio.
+
+- **`autobuild` reserva la tarea antes de construirla y la suelta al cerrarla.** Es lo que hace que dos
+  corridas en paralelo dejen de trabajar lo mismo: entre preguntar qué toca y reservarlo hay una ventana, y
+  perder esa carrera no frena la corrida — relee y sigue con la que quedó libre.
+
+- **El aviso de reclamo viejo mira si la rama avanzó, no cuánto hace que se tomó.** El tiempo transcurrido
+  no distingue una tarea larga de una abandonada, y equivocarse cuesta en los dos sentidos: apurar a quien
+  está trabajando, o dejar bloqueada para siempre la tarea de quien se fue. Ahora `check` mira el último
+  commit **propio** de `task/<tarea>` —los que no están en el tronco, porque una rama recién creada hereda
+  su historia entera y sin esa distinción toda rama parecería haber avanzado el día que se creó—: tres días
+  sin ninguno avisan, y una tarea que recibe commits no se apura nunca
+  aunque lleve semanas tomada. Sin repositorio resoluble el aviso vuelve a mirar sólo la fecha — degrada a
+  lo que había, no rompe.
+
+- **`ops context --hito <slug>` acota la cola a un hito.** Es la forma más barata de que dos personas o dos
+  agentes no se crucen: en hitos distintos casi nunca dependen entre sí ni tocan los mismos archivos. Lo
+  que se acota es qué se ofrece, no qué se sabe — una dependencia que vive en otro hito se sigue juzgando
+  igual—, y un hito mal escrito lo dice en vez de contestar «sin tarea disponible», que es indistinguible
+  de un hito terminado.
+
+- **El plan en vuelo es uno por runner: `planning/wip/<runner>.md`.** Con `mode: sidecar` hay un solo
+  `planning/` por máquina, así que un plan compartido lo escribían todos los agentes que corren ahí: el
+  segundo pisaba el del primero, y `ops context` le entregaba la tarea que el primero estaba construyendo
+  —con el plan ajeno adentro y diciéndole que estaba libre—. `context` honra sólo el tuyo y `check` los
+  recorre todos.
+
+  **Lo que te pide algo**: `planning/WIP.md` se retiró. Mové tu plan a `planning/wip/<runner>.md` —el
+  nombre sale de tu `CAUCE_RUNNER`, aplanado; `ops context --json` lo dice en `wipFile`— y borrá el
+  archivo viejo, que mientras esté `ops check` lo nombra. El `.gitignore` nuevo excluye `planning/wip/*.md`
+  y conserva su README; si venías con la línea de `planning/WIP.md`, cambiala.
+
+- **Un `service:` ambiguo entre varias raíces se nombra en vez de elegirse.** Con más de un
+  `workspaceRoots`, un servicio que existe en dos —`.` existe en todas— resolvía al primero: el árbol de
+  trabajo terminaba en el repositorio que no era, y el aviso de avance miraba las ramas de otro. Ahora
+  `ops worktree` nombra los candidatos y se niega, y el aviso degrada a mirar sólo la fecha.
+
+- **`ops worktree` avisa cuando la instancia está embebida.** Con `mode: embedded` cada árbol se lleva su
+  propia copia de `planning/`, así que los reclamos de un agente no los ve el otro hasta mergear y la
+  coordinación entre varios deja de existir sin que nada falle. No lo frena: un árbol por rama con un solo
+  agente es un uso legítimo.
+
+- **`ops runners <planning>`: qué runners tienen trabajo abierto, para que un agente pueda preguntar.**
+  Elegir con qué runner se arranca es lo primero de una sesión y `ops context` no lo contesta: responde
+  «qué hago» para un runner ya elegido. Sin esa lista, un agente se inventa un id y deja huérfano el
+  trabajo de ayer, o se lo pisa a otro que sigue corriendo.
+
+  **Lo que te pide algo**: nada, y es el punto. `AGENTS.md` le dice al runner que mire esa lista al abrir
+  la sesión, que **pregunte** cuál se retoma o si arranca uno nuevo, y que **exporte el id él mismo**. A
+  una persona no se le pide que escriba una variable de entorno.
+
+- **Tu propio reclamo desde otro runner se reconoce en vez de resolverse solo.** Volver al día siguiente
+  sin reponer `CAUCE_RUNNER` y correr un segundo agente tuyo se ven idénticos desde el archivo, y las dos
+  salidas automáticas rompen trabajo: retomar sola le saca la tarea al otro agente, y crear un runner
+  nuevo deja dos construyendo lo mismo. `ops claim` dice cuál es cuál y con qué id se retoma; `ops context`
+  marca esas tareas como «vos, desde otro runner».
+
+- **La evidencia de una tarea cerrada vive en su propio archivo: `planning/done/<slug>.md`.** Cerrar es lo
+  que más se hace, y mientras la evidencia se acumulaba en un `DONE.md` compartido, cerrar era agregarle
+  una entrada a algo que otro también estaba tocando. Ahora dos personas —o dos agentes— que cierran a la
+  vez escriben archivos distintos: no hay conflicto que resolver ni regla de merge que aplicar.
+
+  La entrada declara `fecha:`, la del cierre. Mientras vivían en un archivo, «la última» era la última del
+  archivo; con archivos sueltos el orden lo daría el listado del directorio, que es alfabético, y la
+  respuesta equivocada se leería igual de bien que la correcta. `ops evidence` sin `--task` ordena por ese
+  campo, y el contrato de una entrada está en `planning/done/README.md`.
+
+  **Lo que te pide algo**: `planning/DONE.md` se retiró. Pasá cada entrada a su propio
+  `planning/done/<slug>.md` con su `fecha:` y borrá el archivo — mientras esté, `ops check` lo dice en vez
+  de ignorarlo, porque un `DONE.md` que ya nadie lee deja a sus épicas sin poder cerrar y a sus historias
+  figurando sin evidencia.
+
+- **`ops archive <NNN>` se retiró; `ops archive human-actions` se queda.** Archivar una épica existía para
+  descongestionar un `DONE.md` que se hinchaba con una entrada por tarea; con un archivo por tarea no hay
+  nada que descongestionar, y mover esos archivos a una carpeta por épica sería reintroducir el movimiento
+  que esto vino a sacar. El comando lo dice, en vez de contestar «la épica debe ser NNN».
+
+- **`(depende: slug)` en una línea de tarea: lo que sigue no se le ofrece a otro.** El orden del BACKLOG
+  era la dependencia y alcanzaba mientras hubiera un runner; con dos, el segundo toma la que sigue mientras
+  el primero construye aquella de la que depende, y las dos ramas se pisan al integrar. Una tarea con
+  dependencias sin cerrar no se ofrece ni se puede tomar, y `context` la muestra con una línea `WAIT` que
+  nombra la dependencia y quién la tiene — una cola trabada no se lee como una cola vacía. `check` rechaza
+  la dependencia que no existe y nombra el ciclo entero cuando lo hay.
+
+- **`ops worktree <planning> <tarea>`: un árbol de trabajo por agente, sin clonar el repositorio.** Resuelve
+  en qué raíz de `workspaceRoots` vive el `service:` de la tarea, crea la rama `task/<slug>` y el árbol al
+  lado, y devuelve la ruta con el `export CAUCE_RUNNER` ya escrito. `git worktree` comparte el mismo `.git`
+  y el mismo historial, así que no hay una segunda copia del repositorio: lo que hay es un segundo
+  directorio de archivos fijado a su rama, y por eso **ningún agente hace `checkout`** sobre el trabajo de
+  otro. Repetirlo devuelve el árbol que ya existe.
+
+- **`.gitattributes`: `DONE.md` y `HUMAN_ACTIONS.md` se concatenan en vez de conflictuar.** Dos personas
+  cerrando trabajo el mismo día chocaban siempre, y ese conflicto no significaba nada: las dos entradas son
+  buenas y van las dos. Lo que `union` no hace es deduplicar, y esa falla ya la atrapa `DONE duplicado`.
+
+- **`planning/delivery/teamwork.md`**: qué comparte el equipo y qué no, por qué dos agentes necesitan un
+  `git worktree` cada uno, cómo repartir trabajo, y qué se rompe primero según el tamaño del equipo.
+
+- **BR-OPS-005 — una tarea, un runner.** La contracara de BR-OPS-001: aquélla impide que un runner lleve dos
+  tareas, ésta que dos runners lleven la misma.
+
+### Cambiado
+
+- **`planning/WIP.md` pasa a ser local y deja de viajar por git.** Existe para recuperar la sesión de quien
+  lo escribió —nadie más puede retomarla— y cambia en cada paso, así que compartirlo era un conflicto por
+  commit a cambio de nada. `check` deja de exigir que exista: ausente se lee como IDLE, que es lo que
+  significa, y un clon nuevo ya no falla por no traerlo.
+
+  **Lo que te pide algo**: el molde nuevo lo gitignorea, pero tu `.gitignore` es tuyo y `upgrade` no lo toca.
+  Para aprovecharlo, agregale `planning/WIP.md` y sacalo del índice con `git rm --cached planning/WIP.md`.
+  Sin hacer nada, todo sigue funcionando como antes.
+
+- **BR-OPS-001 se acota al runner.** Decía que WIP es el mutex sin decir de quién, y con equipo eso se leía
+  como «trabaja uno por vez». Ahora dice que un runner no toma dos tareas; que dos runners no tomen la misma
+  es BR-OPS-005.
+
+## [0.69.0] - 2026-09-07
+
+### Agregado
+
+- **`planning/RECURRING.md`: el trabajo que vuelve se declara una vez.** Actualizar dependencias, revisar
+  quién tiene acceso a producción, mirar el gasto del mes: una fila con su cadencia —`mensual`,
+  `trimestral`, `semestral` o `anual`— y la celda de tarea escrita como la cola de su línea de BACKLOG,
+  así que la aceptación se decide una vez y no se improvisa en cada vuelta.
+
+  **Nada se dispara.** No hay cron ni cola: el vencimiento se calcula cuando alguien corre el CLI, y rueda
+  desde el período que cerró la última vuelta en `DONE.md` en vez de una celda que haya que acordarse de
+  actualizar. `node tools/ops.js recurring planning` dice qué venció, y `--promote <qué>` emite la línea de
+  esa vuelta —la emite y no la escribe: pegarla en `BACKLOG.md` es el acto de promoción—. `check` rechaza
+  la fila ilegible y avisa la vencida sin frenar nada; `context` la nombra con `DUE`. Postergar se escribe
+  a mano con su razón, compra un período, y tres seguidas se avisan porque ahí lo que falla es la cadencia.
+
+  **Lo que te pide algo**: el archivo llega vacío con esta actualización y, hasta que declares una fila, el
+  motor no dice una palabra. Y si tu runner ya está andando, la regla nueva que necesita está en
+  `AGENTS.md`: una recurrencia vencida no la promueve él, por más que `context` la nombre sola.
+
 ## [0.68.0] - 2026-09-07
 
 ### Cambiado

package/README.md

@@ -7,8 +7,10 @@ el contexto de cada empresa vive en su propia instancia.
 ## Qué resuelve
 
 - Una tarea tiene una sola fuente de verdad durante todo su ciclo de vida.
-- Una sesión interrumpida se recupera desde `WIP.md`, sin reconstruir la intención.
+- Una sesión interrumpida se recupera desde el plan del runner en `planning/wip/`, sin reconstruir la intención.
 - Las ideas del agente no entran solas a la cola: quedan en `INBOX.md` hasta promoción humana.
+- El trabajo que vuelve cada tanto se declara una vez en `RECURRING.md`; el CLI dice cuándo venció y
+  nadie lo encola solo.
 - Épicas, criterios, tareas y evidencia son validados de forma determinista.
 - Vive en su propia carpeta `ops/` dentro del repo, como sidecar `proyecto-ops` para varios repos, o
   embebido en la raíz.
@@ -162,8 +164,8 @@ cualquiera de esas formas.
 ## Flujo
 
 ```text
-idea → INBOX → roadmap → BACKLOG → WIP → DONE → done/epic-NNN.md
-                    aprobación     ejecución      archivo histórico
+idea → INBOX → roadmap → BACKLOG → claim → WIP → done/<tarea>.md
+                    aprobación      reserva  ejecución    evidencia
 ```
 
 1. Captura ideas, deuda o lecciones en `INBOX.md`.
@@ -171,9 +173,14 @@ idea → INBOX → roadmap → BACKLOG → WIP → DONE → done/epic-NNN.md
    un recorrido —una etapa por dueño de decisión, con su exit gate— y dejar la épica candidata escrita;
    si falta evidencia o autoridad, para y registra la acción humana en vez de suponer.
 3. Promueve historias listas a un `## Hito` de `BACKLOG.md`.
-4. Un runner toma una sola tarea y persiste su plan en `WIP.md`.
-5. Tras Build, Review, Verify y QA, mueve la entrada a `DONE.md` con evidencia.
-6. Al cerrar la épica, ejecuta `ops archive` para mover su evidencia a un histórico inmutable.
+4. Un runner reclama la tarea con `ops claim`, para que otro no la tome, y persiste su plan en `wip/<runner>.md`.
+5. Tras Build, Review, Verify y QA, escribe la evidencia en `done/<slug>.md` y suelta el reclamo.
+6. Al cerrar la última historia, la épica pasa a `closed`.
+
+Lo que vuelve cada tanto —actualizar dependencias, revisar accesos, mirar el gasto del mes— entra por
+un costado: se declara una vez en `RECURRING.md` con su cadencia, y `ops recurring planning` dice qué
+venció y emite la línea de esa vuelta. Nada se dispara; pegarla en `BACKLOG.md` es el paso 3 de
+arriba, hecho por una persona.
 
 Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contrato completo y
 [template/planning/FLOW.md](template/planning/FLOW.md) para operar el ciclo.

package/automatization/AGENTS.md

@@ -65,6 +65,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/automatization/runners/antigravity/rules/cauce.md

@@ -1,7 +1,7 @@
 # Cauce
 
 Lee y cumple `{{OPS_DIR}}AGENTS.md`, `{{OPS_DIR}}planning/PROTOCOL.md` y `{{OPS_DIR}}planning/rules/system/` antes
-de ejecutar trabajo. `{{OPS_DIR}}planning/WIP.md` es el mutex de
+de ejecutar trabajo. `{{OPS_DIR}}planning/wip/<runner>.md` es el mutex de
 ejecución y `{{OPS_DIR}}planning/AWAITING_REVIEW.md` bloquea una corrida nueva. No promociones ideas desde INBOX, no
 inventes aprobaciones o credenciales y no hagas push ni deploy. Cierra cada tarea con verificación real y
 evidencia en DONE.

package/automatization/runners/claude/CLAUDE.md

@@ -20,5 +20,5 @@ misma pregunta más caro. El arranque busca entender qué es el proyecto y dejar
 intención es viable y propone una épica, y `/autobuild` ejecuta trabajo ya promovido; `/integration-sync` e
 `/integration-promote` gestionan staging local sin escritura remota. Ninguno promueve al BACKLOG.
 
-Antes de iniciar, respeta `{{OPS_DIR}}planning/AWAITING_REVIEW.md` y el mutex de `{{OPS_DIR}}planning/WIP.md`. Si el protocolo y
+Antes de iniciar, respeta `{{OPS_DIR}}planning/AWAITING_REVIEW.md` y el mutex de `{{OPS_DIR}}planning/wip/<runner>.md`. Si el protocolo y
 un workflow difieren, manda el protocolo y la diferencia se registra en `{{OPS_DIR}}planning/INBOX.md`.

package/automatization/runners/codex/AGENTS.md

@@ -15,7 +15,7 @@ Los cinco recorridos llegan como skills en `.agents/skills/` y se invocan con `$
 acá —son referencia, no un runtime compatible—, así que cada recorrido se ejecuta fase por fase
 siguiendo el protocolo.
 
-`{{OPS_DIR}}planning/WIP.md` es el mutex: una sola tarea activa. `{{OPS_DIR}}planning/AWAITING_REVIEW.md`
+`{{OPS_DIR}}planning/wip/<runner>.md` es el mutex: una sola tarea activa. `{{OPS_DIR}}planning/AWAITING_REVIEW.md`
 bloquea una corrida nueva hasta que un humano revise. Nada se promueve desde `INBOX.md` sin aprobación.
 
 Antes de cerrar, corré `node {{OPS_DIR}}tools/ops.js check {{OPS_DIR}}planning`.

package/automatization/runners/gemini/GEMINI.md

@@ -8,7 +8,7 @@
 @{{OPS_DIR}}planning/rules/system/conduct.md
 
 `{{OPS_DIR}}planning/PROTOCOL.md` es la fuente de verdad. Ejecuta `/cauce:autobuild` fase por fase; los
-workflows JS de Claude son referencia, no un runtime compatible. `{{OPS_DIR}}planning/WIP.md` es el mutex
+workflows JS de Claude son referencia, no un runtime compatible. `{{OPS_DIR}}planning/wip/<runner>.md` es el mutex
 y `{{OPS_DIR}}planning/AWAITING_REVIEW.md` bloquea una corrida nueva.
 
 Los hooks de `.gemini/settings.json` son obligatorios y bloquean por su cuenta. **Requieren que la

package/automatization/shared/skills/autobuild/SKILL.md

@@ -3,7 +3,7 @@ name: autobuild
 description: Ejecuta el siguiente hito aprobado siguiendo el protocolo Cauce.
 ---
 
-Lee completos `{{OPS_DIR}}AGENTS.md`, `{{OPS_DIR}}planning/PROTOCOL.md` y `{{OPS_DIR}}planning/WIP.md`. Si existe
+Lee completos `{{OPS_DIR}}AGENTS.md`, `{{OPS_DIR}}planning/PROTOCOL.md` y `{{OPS_DIR}}planning/wip/`. Si existe
 `{{OPS_DIR}}planning/AWAITING_REVIEW.md`, detente y explica la acción humana pendiente. Toma solamente la primera tarea
 aprobada, persiste el estado en WIP y ejecuta Build, Review, Verify y QA en orden. Usa los comandos reales del
 servicio, registra evidencia verificable en DONE y detente en el checkpoint entre hitos. No hagas push ni

package/automatization/workflows/autobuild.js

@@ -21,7 +21,7 @@ export const meta = {
     { title: 'Verify', detail: 'Los gates del servicio y la aceptación que ninguna prueba codifica' },
     { title: 'QA', detail: 'El comportamiento ejercitado como lo ve quien lo usa' },
     { title: 'Commit', detail: 'Conventional Commits, uno por naturaleza del diff, sin push' },
-    { title: 'Done', detail: 'Cierre atómico en DONE con el WIP en IDLE' },
+    { title: 'Done', detail: 'Cierre atómico: evidencia escrita, cola y plan limpios, reserva suelta' },
     { title: 'Closing', detail: 'Check de planning y checkpoint humano del hito' },
   ],
 }
@@ -31,8 +31,8 @@ const CONFIG = `${ROOT}/ops.config.json`
 const P = `${ROOT}/planning`
 const ORG = `${ROOT}/organization`
 const BACKLOG = `${P}/BACKLOG.md`
-const DONE = `${P}/DONE.md`
-const WIP = `${P}/WIP.md`
+// Una tarea cerrada escribe su propio archivo, así que dos corridas en paralelo no comparten ninguno.
+const doneFile = (slug) => `${P}/done/${slug}.md`
 const HUMAN = `${P}/HUMAN_ACTIONS.md`
 const GATE = `${P}/AWAITING_REVIEW.md`
 const ROADMAP = `${P}/roadmap`
@@ -58,8 +58,21 @@ const CONTEXT = {
       properties: { build: { type: 'string' }, review: { type: 'array', items: { type: 'string' } } },
     },
     blockedTasks: { type: 'array', items: { type: 'string' } },
+    // Si la tarea que `context` devolvió ya está reservada a nombre de este runner. Libre no significa
+    // que sea nuestra: significa que todavía la puede tomar cualquiera, y dos corridas en paralelo la
+    // reciben las dos.
+    claimed: { type: 'boolean' },
+    // La fecha de hoy según el motor. Este recorrido no tiene reloj propio a propósito.
+    today: { type: 'string' },
+    // Dónde va el plan de este runner. El nombre sale de su id y el recorrido no lo deriva: lo
+    // pregunta, igual que la fecha.
+    wipFile: { type: 'string' },
   },
 }
+const CLAIM = {
+  type: 'object', additionalProperties: false, required: ['claimed'],
+  properties: { claimed: { type: 'boolean' }, details: { type: 'string' } },
+}
 const EXPANSION = {
   type: 'object', additionalProperties: false, required: ['expanded'],
   properties: { expanded: { type: 'boolean' }, hito: { type: 'string' }, reason: { type: 'string' } },
@@ -311,7 +324,10 @@ const write = (prompt, options = {}) => agent(`${LEDGER}\n\n${prompt}`, options)
 // WIP y HUMAN_ACTIONS nunca entran al contexto de un modelo, y su tamaño deja de costar tokens.
 const readContext = () => read(
   `Corré "node tools/ops.js context ${P} --json" desde ${ROOT} y reportá sólo lo que imprimió. Derivá hasTask ` +
-  `de si task es null, wipActive de si wip es null y lane de task.tier; copiá slug, hito, service, acceptance, ` +
+  `de si task es null, wipActive de si wip es null, claimed del campo claimed, today y wipFile de sus ` +
+  `campos, y lane ` +
+  `de task.tier; copiá slug, ` +
+  `hito, service, acceptance, ` +
   `epic y cast de task, y epicContext de epic.context —vacío si no hay épica—. El comando es la fuente de ` +
   `verdad: no abras archivos de planning para completarlo.`,
   { schema: CONTEXT, label: 'planning-context' },
@@ -351,6 +367,24 @@ while (rounds++ < MAX_TASKS) {
     id: planning.slug, hito: planning.hito, service: planning.service,
     acceptance: planning.acceptance, epic: planning.epic, epicContext: planning.epicContext || '',
   }
+  // Reservar antes de construir, y antes de fijar el hito de la corrida. Sin esto dos corridas en
+  // paralelo trabajan la misma tarea: `context` sólo puede saltear lo que alguien ya reclamó, y el
+  // primero en preguntar todavía no reclamó nada. La ventana entre preguntar y reservar existe igual, y
+  // por eso perder la carrera no es un error: se relee y se sigue con la que quedó libre.
+  if (!planning.claimed && !planning.wipActive) {
+    phase('Claim')
+    const reserva = await write(
+      `Corré "node tools/ops.js claim ${P} ${task.id}" desde ${ROOT}. No escribas ningún archivo vos: lo ` +
+      `escribe el comando. claimed=true sólo con exit 0; si falla porque la tomó otro, claimed=false y ` +
+      `copiá el mensaje en details.`,
+      { schema: CLAIM, label: `claim:${task.id}` },
+    )
+    if (!reserva || !reserva.claimed) {
+      planning = await readContext()
+      if (!planning) return stop('context-unavailable', `no se pudo releer el estado de ${P}`)
+      continue
+    }
+  }
   currentMilestone = task.hito
 
   // Ver la tarea y, si no está clasificada, clasificarla antes de ejecutarla. Se hace una vez por
@@ -535,7 +569,7 @@ while (rounds++ < MAX_TASKS) {
     `dio; recién después implementá. Un test que pasa antes de que exista el código no asercia lo que dice ` +
     `aserciar: endurecelo y volvé a correr hasta verlo fallar. Corré las pruebas que necesites para ver ese ` +
     `rojo y ese verde, y nada más: los gates completos, el QA, el commit y el cierre son fases posteriores, ` +
-    `así que no toques ${DONE} ni ${BACKLOG} ni el status del WIP. Lo que el plan no previó va en discovered y ` +
+    `así que no toques ${P}/done/ ni ${BACKLOG} ni el status del WIP. Lo que el plan no previó va en discovered y ` +
     `no en el código a secas: kind=edge si esta tarea lo puede fijar —y entonces entra con su prueba, que ` +
     `nombrás en test y anotás en redFirst—, kind=open si lo notaste y no impide entregar la aceptación: se ` +
     `registra para que lo decida quien corresponde y el recorrido sigue. Si de verdad no podés entregar sin ` +
@@ -693,9 +727,11 @@ while (rounds++ < MAX_TASKS) {
 
   phase('Done')
   await write(
-    `Cerrá ${task.id} de forma atómica: agregala bajo su hito en ${DONE} con evidencia de acept, done, qa, ` +
-    `tests y commit; sacala junto con sus notas indentadas de ${BACKLOG}; cerrá su épica sólo si no queda ` +
-    `ninguna tarea etiquetada; y dejá ${WIP} en status IDLE. En decisions no nombres una fase ni un cargo ` +
+    `Cerrá ${task.id} de forma atómica: escribí ${doneFile(task.id)} con su evidencia —acept, ` +
+    `fecha: ${planning.today}, done, qa, tests y commit, en el formato de entrada que trae este preámbulo—; ` +
+    `sacala junto con sus notas indentadas de ${BACKLOG}; cerrá su épica sólo si no queda ` +
+    `ninguna tarea etiquetada; dejá ${P}/${planning.wipFile} en status IDLE; y soltá la reserva corriendo ` +
+    `"node tools/ops.js release ${P} ${task.id}". En decisions no nombres una fase ni un cargo ` +
     `que no figure en estos hechos. Hechos: lane=${planning.lane || 'sin clasificar'}; ` +
     `review=${reviewFact}; fases=${ran.join(' → ')}; build=${build.summary}; ` +
     `verify=${JSON.stringify(verified.commands)}; qa=${qa.evidence}; commit=${commit.hash || commit.reason}.`,

package/engine/cli/archive.js

@@ -0,0 +1,87 @@
+'use strict'
+
+// Los comandos que mueven estado ya decidido: archivar lo que cerró y declarar de una vez qué historia
+// llegó con el proyecto. Viven aparte de `planning.js` porque son la otra mitad de una costura: aquéllos
+// leen y juzgan sin mutar nada, éstos escriben. 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('../planning/parser')
+const PC = require('../planning/contracts')
+const AD = require('../planning/adoption')
+const F = require('../core/files')
+const { fail } = require('./io')
+
+// La fecha de hoy, la misma que usan los comandos que leen.
+const TODAY = () => new Date().toISOString().slice(0, 10)
+
+// El historial de acciones humanas se acumula en un solo archivo y no por épica: una fila no pertenece
+// a ninguna, y esperar el cierre de una épica dejaría sin archivar las de un planning que todavía no
+// cerró ninguna —que es justo cuando el archivo se vuelve ilegible—.
+// Adoptar es declarar de una vez qué historia llegó con el proyecto. Se genera con lo que hoy no cumple
+// y no se vuelve a correr: un baseline que se regenera perdona de nuevo lo que alguien ya se tomó el
+// trabajo de arreglar, y uno que crece a mano deja de ser una lista de perdones para ser una amnistía.
+// Achicarlo sí es a mano, borrando el renglón que `check` señala.
+function adopt(dir) {
+  const root = path.resolve(dir || '.')
+  const target = path.join(root, AD.BASELINE)
+  if (fs.existsSync(target)) {
+    // Un baseline que ya trae huella no se toca: regenerarlo es exactamente lo que la huella impide.
+    // Uno sin huella lo generó una versión anterior, y sellarlo no es regenerar nada — se calcula sobre
+    // lo que ya está—, así que es la única salida de un aviso que si no no tendría ninguna.
+    const existing = fs.readFileSync(target, 'utf8')
+    if (!AD.sealWarnings(root).some((one) => /sin huella/.test(one))) {
+      fail(`${AD.BASELINE} ya existe: se genera una vez. Para retirar un renglón, ponele \`#~\` `
+        + 'delante; `check` marca los que ya cumplen.')
+    }
+    const slugs = AD.declared(existing)
+    F.atomicWrite(target, existing.replace(/\n?$/, `\n# huella: ${slugs.length} entradas · `
+      + `sha256:${AD.digest(slugs)}\n`))
+    return console.log(`✓ ${AD.BASELINE} sellado con ${slugs.length} entrada(s); la lista no cambió`)
+  }
+  const epics = P.readEpics(root)
+  const pending = P.readDone(root).entries.filter((entry) => PC.doneEntryErrors(entry, epics).length)
+  if (!pending.length) {
+    return console.log('= no hay nada que exentar: todas las entradas de DONE cumplen el contrato')
+  }
+  const today = TODAY()
+  const slugs = pending.map((entry) => entry.slug)
+  F.atomicWrite(target, `# Entradas anteriores a la adopción de Cauce (${today}). No se agregan nuevas:\n`
+    + '# desde esa fecha rige el contrato completo, y `check` avisa cuando una de éstas pasa a\n'
+    + '# cumplirlo para que le pongas `#~` delante y quede retirada.\n'
+    + `# huella: ${slugs.length} entradas · sha256:${AD.digest(slugs)}\n`
+    + `${slugs.join('\n')}\n`)
+  console.log(`✓ ${pending.length} entrada(s) exentas en ${AD.BASELINE}`)
+  return console.log('  revisá la lista: lo que sí cumple el contrato no tiene por qué estar ahí')
+}
+
+function archiveHumanActions(root) {
+  const source = path.join(root, 'HUMAN_ACTIONS.md')
+  const rows = P.readHumanActions(root).filter((row) => row.resolved)
+  if (!rows.length) return console.log('= no hay filas resueltas')
+  const target = path.join(root, 'done', 'human-actions.md')
+  const header = '| Tarea | Estado | Origen | Acción concreta y condición de desbloqueo |\n|---|---|---|---|'
+  const previous = P.read(target).trimEnd()
+  const head = previous || `---\nstatus: archived\n---\n\n# Acciones humanas resueltas\n\n${header}`
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  F.atomicWrite(target, `${head}\n${rows.map((row) => row.raw).join('\n')}\n`)
+  const drop = new Set(rows.map((row) => row.raw))
+  const kept = P.read(source).split('\n').filter((line) => !drop.has(line))
+  F.atomicWrite(source, `${kept.join('\n').trimEnd()}\n`)
+  return console.log(`✓ ${rows.length} fila(s) archivadas`)
+}
+// Archivar una épica se retiró en 0.71.0. Existía para descongestionar un `DONE.md` que se hinchaba con
+// una entrada por tarea; con un archivo por tarea no hay nada que descongestionar, y mover esos archivos
+// a una carpeta por épica sería reintroducir el movimiento que la mudanza vino a sacar.
+//
+// El comando se queda para lo que sí sigue archivándose, y para decirle a quien escriba el número que ya
+// no hace falta: sin esto contestaría «La épica debe ser NNN», que manda a corregir la forma de algo que
+// no existe.
+function archive(dir, rawNum) {
+  if (String(rawNum || '') === 'human-actions') return archiveHumanActions(path.resolve(dir || '.'))
+  return fail('Sólo se archiva `human-actions`. La evidencia de una tarea ya vive en su propio archivo '
+    + 'de `done/`, así que archivar una épica dejó de tener sentido.', 2)
+}
+
+module.exports = { archive, adopt }

package/engine/cli/args.js

@@ -7,7 +7,7 @@
 // Banderas que consumen el argumento siguiente: su valor no es un posicional.
 const VALUED_FLAGS = new Set([
   '--name', '--mode', '--fixture', '--period', '--record', '--runner', '--integration',
-  '--task',
+  '--task', '--promote', '--hito',
 ])
 
 // Qué acepta cada comando, y a la vez qué comandos existen. Una bandera desconocida se rechaza en vez
@@ -19,7 +19,12 @@ const FLAGS = {
   onboard: ['--json'],
   check: ['--json'],
   tree: ['--json', '--no-color'],
-  context: ['--json'],
+  context: ['--json', '--hito'],
+  recurring: ['--json', '--promote'],
+  claim: ['--json'],
+  runners: ['--json'],
+  worktree: ['--json'],
+  release: [],
   evidence: ['--json', '--task'],
   upgrade: ['--check', '--force'],
   destroy: ['--force'],

package/engine/cli/catalog.js

@@ -115,7 +115,15 @@ function evaluationBench(root, agent, caso, force, kind) {
   // sin pagar un `npm install` por corrida. El cargo llega a un banco donde el CLI funciona.
   const scope = path.join(dir, 'node_modules', '@ingeniomaps')
   fs.mkdirSync(scope, { recursive: true })
-  fs.symlinkSync(IN.PROJECT_ROOT, path.join(scope, 'cauce'), 'dir')
+  // El enlace se pisa por lo mismo que el andamiaje de arriba: a veces sobrevive al borrado del banco, y
+  // entonces crearlo corta la corrida con `EEXIST` en vez de rehacerlo. Es el único paso que no seguía esa
+  // regla, y el que falló en CI rehaciendo el mismo `11-otro` que ya tiene reintentos por esto.
+  //
+  // `rmSync` sobre un enlace lo quita a él y no a lo que apunta —que acá es la raíz del toolkit—, así que
+  // esto no puede llevarse por delante el repositorio.
+  const link = path.join(scope, 'cauce')
+  fs.rmSync(link, { force: true })
+  fs.symlinkSync(IN.PROJECT_ROOT, link, 'dir')
 
   // El artefacto del caso, si lo tiene: la guía del proveedor que el pedido manda implementar, el CSV
   // con instrucciones adentro. Entra antes del commit limpio a propósito — si entrara después, `status`

package/engine/cli/claims.js

@@ -0,0 +1,125 @@
+'use strict'
+
+// Tomar y soltar una tarea, y ver quién tiene trabajo abierto. Los dos primeros son los únicos comandos
+// del motor que escriben un archivo de coordinación, y escriben **el propio**: `BACKLOG.md` no lo toca
+// ninguno, porque la cola es de lo aprobado y la escribe una persona.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const CL = require('../planning/claims')
+const R = require('../core/repos')
+const ST = require('../planning/state')
+const { fail } = require('./io')
+
+const TODAY = () => new Date().toISOString().slice(0, 10)
+
+function claim(dir, slug, cli) {
+  const root = path.resolve(dir || '.')
+  if (!slug) return fail('Falta el slug. `ops claim <planning-dir> <tarea>`', 2)
+  const state = ST.snapshot(root)
+  const task = state.milestones.flatMap((milestone) => milestone.tasks).find((one) => one.slug === slug)
+  if (!task) return fail(`${slug} no está en BACKLOG: sólo se toma trabajo ya promovido.`, 2)
+
+  // No se reserva lo que todavía no se puede empezar: una tarea tomada con su dependencia en vuelo
+  // bloquea la cola sin que nadie pueda avanzarla, y el runner que la tomó se queda sin poder tomar otra.
+  const falta = task.depends.find((dep) => !state.done.set.has(dep))
+  if (falta) return fail(`${slug} depende de ${falta}, que todavía no está en DONE.`)
+
+  const me = CL.owner(root)
+  const from = CL.runner()
+  if (!me) {
+    return fail('No sé quién sos. Configurá `git config user.email` o exportá CAUCE_OWNER: '
+      + 'un reclamo anónimo no dice a quién preguntarle.', 2)
+  }
+  // Un runner lleva una tarea a la vez (BR-OPS-001), y exigirlo acá hace ruidosa la única forma en que
+  // este contrato falla en silencio: dos agentes de la misma máquina compartiendo id porque nadie puso
+  // `CAUCE_RUNNER`. Sin esto, el segundo se llevaría la tarea del primero creyéndola suya.
+  //
+  // La que se está pidiendo queda afuera del conteo: volver a pedir la propia es reintentar, no llevar dos.
+  const ocupado = state.claims
+    .find((one) => one.runner === from && one.slug !== slug && !state.done.set.has(one.slug))
+  if (ocupado) {
+    return fail(`este runner ya tiene ${ocupado.slug}. Cerrala o soltala primero; y si sos otro agente `
+      + 'en la misma máquina, exportá CAUCE_RUNNER con un valor propio.')
+  }
+
+  const target = CL.file(root, slug)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  const cuerpo = CL.content({ task: slug, owner: me, runner: from, started: TODAY(), service: task.service })
+  try {
+    // Reservar **es** crear el archivo, así que el único juez de quién la tiene es el archivo. `wx` falla
+    // si ya está, y de ahí sale la respuesta entera: propia, ajena o perdida en la carrera.
+    //
+    // Sin `wx` no habría reserva: `atomicWrite` renombra encima, y dos agentes que arrancan con segundos
+    // de diferencia ganarían los dos sin que ninguno se entere. Y una comprobación previa tampoco
+    // alcanzaría —entre mirar y escribir queda la misma ventana—, así que sería un segundo juez que
+    // adelanta un veredicto que este bloque tiene que volver a dar igual.
+    fs.writeFileSync(target, cuerpo, { flag: 'wx' })
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    const dueño = CL.read(root).find((one) => one.slug === slug)
+    // Existía al crear y ya no está: alguien la soltó entre las dos operaciones. Es una ventana de
+    // microsegundos y aun así tiene respuesta, porque la alternativa es reventar con un TypeError.
+    if (!dueño) return fail(`${slug} cambió de manos mientras la pedías; volvé a intentarlo.`)
+    if (dueño.runner === from) return console.log(`= ${slug} ya era tuya desde ${dueño.started}`)
+    // Mismo dueño y otro runner son dos situaciones que se ven idénticas desde acá —vos retomando la
+    // sesión de ayer, o un segundo agente tuyo— y ninguna se puede distinguir mirando el archivo.
+    // Retomarla sola le sacaría la tarea al otro agente; crear un runner nuevo dejaría dos trabajando lo
+    // mismo. Las dos rompen trabajo, así que decide una persona y acá sólo se dice cuál es cuál.
+    if (dueño.owner === me) {
+      return fail(`${slug} la tenés vos, tomada el ${dueño.started} desde el runner ${dueño.runner}. `
+        + 'Preguntá si se retoma esa sesión —y entonces corré con ese id— o si es otro agente en '
+        + `paralelo, que toma otra tarea. \`ops runners ${path.relative(process.cwd(), root) || '.'}\` `
+        + 'lista lo que hay abierto.')
+    }
+    return fail(`${slug} la tomó ${dueño.owner} el ${dueño.started}. Si se abandonó, borrá `
+      + `${CL.DIR}/${slug}.md a mano: soltar lo de otro es una decisión, no un comando.`)
+  }
+  console.log(`✓ ${slug} tomada por ${me}`)
+  // Un reclamo sin empujar no protege de nada: el otro runner lee lo que hay en su copia. Decirlo acá
+  // es lo único que separa «tomé la tarea» de «creí que la había tomado».
+  if (!cli.has('--json')) console.log(`  commiteá y empujá ${CL.DIR}/${slug}.md para que el equipo lo vea`)
+}
+
+function release(dir, slug) {
+  const root = path.resolve(dir || '.')
+  if (!slug) return fail('Falta el slug. `ops release <planning-dir> <tarea>`', 2)
+  const from = CL.runner()
+  const taken = CL.read(root).find((one) => one.slug === slug)
+  if (!taken) return fail(`${slug} no está tomada por nadie.`, 2)
+  if (taken.runner !== from) {
+    return fail(`${slug} es de ${taken.owner}. Si se abandonó, borrá ${taken.at} a mano.`)
+  }
+  fs.rmSync(CL.file(root, slug))
+  console.log(`✓ ${slug} soltada; volvió a la cola`)
+}
+
+// Qué runners tienen trabajo abierto, para que un agente pueda preguntar antes de inventarse un id.
+//
+// Es lo primero de una sesión y no lo contesta `context`: `context` responde «qué hago» para un runner ya
+// elegido, y elegirlo viene antes. Sin esta lista, un agente que arranca sin `CAUCE_RUNNER` se crea uno
+// nuevo y deja el trabajo de ayer huérfano, o peor, se lo pisa a otro agente que sigue corriendo.
+//
+// La persona elige; el agente exporta. Pedirle a una persona que escriba una variable de entorno para
+// retomar su propio trabajo es hacerle hacer de intérprete.
+function runners(dir, cli) {
+  const root = path.resolve(dir || '.')
+  const done = ST.snapshot(root).done
+  const abiertos = CL.read(root).filter((one) => !done.set.has(one.slug))
+  const hoy = TODAY()
+  const filas = abiertos.map((one) => {
+    const commit = R.lastCommit(R.repoOf(path.join(root, '..'), one.service), CL.branchOf(one.slug))
+    return { runner: one.runner, task: one.slug, owner: one.owner, started: one.started, lastCommit: commit }
+  })
+  if (cli.has('--json')) return console.log(JSON.stringify(filas))
+  if (!filas.length) return console.log('= ningún runner tiene trabajo abierto: arrancá con un id propio')
+  const ancho = Math.max(...filas.map((one) => one.runner.length))
+  for (const una of filas) {
+    const avance = una.lastCommit ? `último commit ${una.lastCommit}` : 'sin commits en su rama'
+    console.log(`${una.runner.padEnd(ancho)}  ${una.task}  (${una.owner}, desde ${una.started}; ${avance})`)
+  }
+  console.log(`\n${filas.length} runner(s) con trabajo abierto al ${hoy}. `
+    + 'Retomá uno usando su id, o arrancá con uno propio.')
+}
+
+module.exports = { claim, release, runners }