@ingeniomaps/cauce 0.69.0 → 0.70.0

package/template/planning/delivery/multi-repo.md

@@ -19,6 +19,17 @@ manifiesto es evidencia del pipeline, no una lista que una persona edita manualm
 - Bases de datos y APIs aplican expand/contract durante la ventana de convivencia.
 - Una entrega cross-repo registra qué PR y versión satisface cada lado del contrato.
 
+## El `service:` de una tarea tiene que resolver a un solo repositorio
+
+Con varias raíces declaradas, un `service:` que existe en más de una es ambiguo: `.` existe en todas, y un
+`src` puede existir en dos. `ops worktree` lo nombra y se niega en vez de elegir la primera, porque elegir
+da una respuesta plausible y equivocada —el árbol de trabajo en el repositorio que no era— sin que nada lo
+diga. El aviso de avance de un reclamo degrada por lo mismo: sin poder resolver el repositorio, mira sólo
+la fecha en que se tomó.
+
+La salida es escribir servicios que sólo existan en una raíz. Si dos repositorios tienen un directorio con
+el mismo nombre y los dos son servicios de verdad, conviene una instancia por repositorio.
+
 ## Cuándo coordinar
 
 Coordinar solo cuando una propiedad no puede preservarse mediante compatibilidad temporal, por ejemplo una

package/template/planning/delivery/teamwork.md

@@ -0,0 +1,162 @@
+# Trabajo en equipo
+
+> Camino recomendado. Adaptar en `project.md` y registrar excepciones durables mediante ADR.
+
+Una instancia la comparte un equipo, y lo que comparte es de tres clases distintas. Casi todos los
+choques entre dos personas —o entre dos agentes— salen de tratarlas igual.
+
+## Los tres anillos
+
+| Anillo | Qué vive ahí | Escritores | Frecuencia |
+|---|---|---|---|
+| **Compartido** | `roadmap/`, `BACKLOG.md`, `INBOX.md`, `HUMAN_ACTIONS.md`, `done/`, reglas y ADR | cualquiera, en actos humanos | baja |
+| **Coordinación** | `claims/`, un archivo por tarea tomada | uno por tarea | dos veces por tarea |
+| **Local** | `wip/<runner>.md`, `.verify-log`, el árbol de trabajo | vos | continua |
+
+La regla que los separa: **un archivo con más de un escritor tiene que cambiar poco; uno que cambia mucho
+tiene que tener un solo escritor.** Cuando uno viola las dos a la vez, el equipo se pisa en cada commit.
+
+De ahí sale el corolario que ahorra la mayor parte de las conversaciones: **no hace falta que cada persona
+sepa qué está haciendo la otra.** Hacen falta dos cosas y sólo dos — qué está tomado, para no tomarlo dos
+veces, y qué terminó, porque es evidencia y destraba lo que dependía de eso. Todo lo del medio —el plan,
+los pasos, las decisiones en vuelo— no le sirve a nadie más y es justo lo que más cambia.
+
+## Un árbol de trabajo por persona o por agente
+
+Dos agentes en el mismo directorio comparten índice de git y archivos: uno stagea lo del otro, uno
+commitea trabajo ajeno, y los errores no se parecen a la causa — un archivo trackeado que «no existe»
+suele ser la otra sesión y no tu cambio. No es un problema de este toolkit sino del filesystem, y la
+respuesta es un árbol por cada uno:
+
+```bash
+git worktree add ../repo-dashboard  feat/dashboard-filtros
+git worktree add ../repo-exportar   feat/boton-exportar
+```
+
+Mismo `.git`, índices separados, archivos separados. Es la **precondición** para correr dos agentes a la
+vez: sin esto, nada de lo demás de esta guía alcanza.
+
+Cada árbol necesita además sus propios recursos —puertos, contenedores, base—. Dos agentes levantando el
+mismo entorno de desarrollo en el mismo puerto fallan mucho antes que cualquier archivo de planning.
+
+La rama por tarea y su ciclo viven en `branches.md`; acá se agrega que el árbol también se separa.
+
+## Tomar una tarea sin pisarse
+
+Tomar es un acto y tiene comando:
+
+```bash
+node tools/ops.js claim planning dashboard-filtros
+node tools/ops.js release planning dashboard-filtros
+```
+
+`ops context` no ofrece una tarea con reclamo ajeno y nombra quién la tiene, así que dos runners
+preguntando a la vez ya no reciben la misma. Y devuelve antes lo que vos reclamaste que lo que está
+libre: es lo que dijiste que ibas a hacer. El contrato completo está en `../claims/README.md`.
+
+Lo que el comando **no** hace, y hay que saberlo: un reclamo sin empujar no reserva nada, porque el otro
+runner lee lo que hay en su copia. Entre `claim` y el push hay una ventana, y es de minutos sólo si se
+commitea el reclamo enseguida.
+
+**Lo que sigue a una tarea en vuelo no se le ofrece a nadie más.** Una tarea puede declarar
+`(depende: slug)`, y mientras eso no esté en DONE no se ofrece ni se puede tomar: el trabajo que sigue es
+de quien tiene la cabeza, y dárselo a otro produce dos ramas que se pisan al integrar. `context` lo dice
+con una línea `WAIT` que nombra la dependencia y quién la tiene, para que la cola trabada no se lea como
+una cola vacía. `check` rechaza una dependencia que no existe y nombra el ciclo entero cuando lo hay.
+
+Dos cosas que el mecanismo no reemplaza:
+
+- **Mirar el `service:`.** Es el dominio de colisión y ya está declarado en cada tarea: dos tareas de
+  servicios distintos no se pueden pisar en el código, dos del mismo pueden. `ops check` avisa cuando hay
+  dos reclamos sobre el mismo servicio, y avisa nada más — frenar serializaría a un equipo entero sobre
+  un servicio, que es peor que la colisión que evita.
+- **Repartir por hito.** Cada persona toma de un `## Hito` distinto, y `ops context planning --hito <slug>`
+  acota la cola a ése. Dos personas en hitos distintos casi nunca dependen entre sí ni tocan los mismos
+  archivos, así que los dos avisos de arriba casi no aparecen.
+
+## Varios agentes en una misma máquina
+
+Una tarea larga deja horas muertas, y ese hueco alcanza para poner otro agente a trabajar. Cuatro cosas
+lo hacen posible, y ninguna pide clonar el repositorio dos veces.
+
+**Un clon, varios árboles de trabajo.** `git worktree` no clona: comparte el mismo `.git`, el mismo
+historial y los mismos objetos, y sólo materializa un segundo directorio de archivos. Cada árbol queda
+fijado a su rama, así que **nadie hace `checkout` nunca** — que es lo que pisaría el trabajo del otro.
+
+```bash
+node tools/ops.js worktree planning dashboard-filtros
+```
+
+Resuelve en qué repositorio 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. Correrlo dos veces devuelve el árbol que
+ya existe en vez de crear otro.
+
+**La instancia, una sola y compartida.** Si `ops/` vive dentro del repositorio (`mode: embedded`), cada
+árbol se lleva su propia copia de `planning/` — o ninguna, si todavía no se commiteó— y los reclamos de un
+agente no los ve el otro hasta mergear: justo la coordinación que en una máquina tendría que ser
+instantánea. Con `mode: sidecar` la instancia es una, al lado de los repos, y los reclamos se ven al
+momento y sin git de por medio.
+
+`ops worktree` lo avisa cuando prepara un árbol sobre una instancia embebida. No lo frena: un árbol por
+rama con un solo agente es un uso legítimo, y lo que se rompe es la coordinación entre varios.
+
+**Un id por agente.** Sin eso los dos resuelven la misma identidad de git y el segundo toma por propia la
+tarea del primero. Al abrir una sesión, `ops runners planning` dice qué runners tienen trabajo abierto;
+el agente pregunta cuál se retoma o si arranca uno nuevo, y **exporta el id él mismo**. A una persona no
+se le pide que escriba una variable de entorno. El contrato está en `../claims/README.md`.
+
+**Recursos propios.** Puertos, contenedores y base por agente. Dos sesiones levantando el mismo entorno
+en el mismo puerto fallan antes que cualquier archivo de planning.
+
+Sirve igual para dos agentes de la misma herramienta o de herramientas distintas: la reserva es del CLI,
+no del runner que la invoca.
+
+## Pasar una tarea a otra persona
+
+El plan es local, así que no viaja: quien recibe la tarea ve el reclamo y no cómo venía pensada. Eso está
+bien casi siempre —nadie necesita el plan de otro— y falla justo cuando hace falta.
+
+Por eso el traspaso es un acto y tiene tres pasos: quien deja **publica su plan** donde el otro lo lea —una
+nota en la tarea, un mensaje, lo que el equipo use—, suelta el reclamo, y quien toma lo reclama. El costo
+de compartir el plan se paga entonces, que es cuando sirve.
+
+Lo que no hay que hacer es empujar tu `wip/<runner>.md`: sería devolver a git el archivo que más cambia,
+todos los días, para resolver algo que pasa una vez cada tanto.
+
+## Cuando el equipo crece o se achica
+
+**No se escala por archivo: se escala por instancia.** Los umbrales no son leyes; son el momento de mirar.
+
+| Tamaño | Qué alcanza | Qué se rompe primero |
+|---|---|---|
+| 1 | todo tal cual | nada |
+| 2 a 8 | un `planning/`, un árbol por persona, reparto por hito | sacar la tarea de `BACKLOG.md` al cerrarla, que es lo único que dos personas se disputan |
+| 8 a 20 | lo mismo, con la cola acotada por hito (`--hito`) | el `BACKLOG` se vuelve **ilegible** antes que contencioso: nadie lee sesenta tareas para elegir la suya, y acotar por hito ayuda sólo si los hitos están bien cortados |
+| 20+ | una instancia por equipo o por dominio | la coordinación pasa a ser entre instancias, que es `multi-repo.md` |
+
+Achicarse parece más fácil y tiene una trampa: **lo que tomó quien se fue no se libera solo.** `ops check`
+avisa a los tres días sin que la rama de la tarea se mueva —una tarea larga que avanza no se apura—, pero
+soltarlo es borrar el archivo de `claims/` a mano — `ops release` se niega a
+hacerlo por vos—. Al bajar de tamaño se recorren esos reclamos igual que las filas de `HUMAN_ACTIONS.md`
+que esperaban a esa persona.
+
+## Dónde va cada cosa que el equipo se dice
+
+| Lo que pasó | Dónde va | Por qué ahí |
+|---|---|---|
+| Una decisión que cambia cómo se construye | `adr/` | se consulta dentro de un año |
+| Una norma que hay que cumplir siempre | `business-rules/` o `rules/` | la lee un agente en cada tarea |
+| Algo que sólo puede hacer una persona | `HUMAN_ACTIONS.md` | frena su tarea hasta que se resuelva |
+| Una idea, una deuda, una lección | `INBOX.md` | espera promoción humana |
+| Lo que una tarea entregó, con su evidencia | `done/<slug>.md` | es lo que se audita |
+| Qué tarea estoy haciendo | `claims/` | para que nadie la tome dos veces |
+| «Salgo a almorzar», «está lento el CI» | el canal del equipo | no es durable y no se audita |
+
+La última fila pesa tanto como las otras: meter conversación en el repositorio lo vuelve ilegible, y sacar
+decisiones del repositorio las pierde.
+
+## Lo que git tiene que saber
+
+`.gitattributes` declara que `HUMAN_ACTIONS.md` y su histórico se concatenan en vez de conflictuar cuando
+dos personas registran un bloqueo el mismo día. Llega con la instancia y sus bordes están escritos ahí
+adentro. La evidencia de una tarea no lo necesita: vive en su propio archivo y nadie escribe el de nadie.

package/template/planning/done/README.md

@@ -0,0 +1,41 @@
+# Evidencia de lo terminado
+
+Un archivo por tarea cerrada, con el slug de la tarea como nombre: `alta-de-cliente.md` es lo que esa
+tarea entregó y con qué se comprueba.
+
+```markdown
+- [x] **alta-de-cliente** (epic: 001) — Alta de cliente
+  acept: el alta rechaza un duplicado
+  fecha: 2026-09-08
+  done: cambios y comandos de verificación con exit codes
+  qa: comportamiento observado por el camino real
+  tests: C1 → nombre de prueba o comando; C2 → nombre de prueba o comando
+  decisions: decisión no obvia [fuente: ruta/archivo] o [supuesto: motivo verificable]
+  commit: abc1234 feat(scope): subject (repo@branch)
+```
+
+El contrato completo de esos campos está en `../PROTOCOL.md`; acá va por qué el archivo es uno por tarea.
+
+## Por qué uno por tarea
+
+Cerrar es lo que más se hace, y mientras la evidencia se acumulaba en un archivo compartido, cerrar era
+agregarle una entrada a algo que otro también estaba tocando. Con un archivo por tarea, **dos personas
+—o dos agentes— que cierran a la vez escriben archivos distintos**: no hay conflicto que resolver ni
+regla de merge que aplicar.
+
+El nombre del archivo es una conveniencia; lo que identifica la tarea es el slug de la viñeta. Renombrar
+el archivo no cambia de qué tarea habla, y cerrar dos veces la misma sigue siendo un error que `check`
+rechaza, ahora entre archivos.
+
+## Por qué la fecha
+
+Mientras las entradas 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: la respuesta equivocada se leería igual
+de bien que la correcta. Por eso `fecha:` es la del cierre y es obligatoria — y por eso `ops evidence`
+sin `--task` puede contestar por la más reciente.
+
+## Qué más vive acá
+
+`human-actions.md`, con las filas resueltas que `ops archive human-actions` mueve desde
+`../HUMAN_ACTIONS.md`. Es una tabla y no una entrada, así que el lector no la confunde con una tarea —
+igual que a este README—.

package/template/planning/wip/README.md

@@ -0,0 +1,49 @@
+# El plan en vuelo
+
+Un archivo por runner: `wip/<runner>.md` es el plan de quien lo escribió, y **no viaja por git**. Existe
+para recuperar esa sesión si se corta, y nadie más puede retomarla — el árbol de trabajo es otro.
+
+```markdown
+---
+task: slug
+hito: "Hito slug — Título"
+epic: 001
+phase: Build
+started: AAAA-MM-DD
+service: ruta
+acceptance: "criterio observable"
+---
+
+## Plan aprobado
+1. [ ] Paso verificable
+
+## Decisiones tomadas
+- (ninguna)
+
+## Bloqueos
+- (ninguno)
+```
+
+Sin archivo, el runner está en IDLE: un clon nuevo no trae ninguno y eso no es un error.
+
+## Por qué uno por runner y no uno solo
+
+Con `mode: sidecar` hay un solo `planning/` por máquina, así que un archivo compartido lo escriben todos
+los agentes que corren ahí: el segundo pisa el plan del primero, y `ops context` le entrega la tarea que
+el primero está construyendo — con el plan ajeno adentro y diciéndole que está libre.
+
+El nombre sale del id del runner, aplanado para poder ser un nombre de archivo. Queda largo y legible a
+propósito: sirve para ver de quién es cada plan cuando algo quedó a medias.
+
+## Qué mira cada comando
+
+`ops context` honra **sólo el tuyo**, que es el único que te corresponde continuar, y `ops check` los
+recorre todos — que cada plan apunte a una tarea que existe es una pregunta sobre la instancia, no sobre
+quien pregunta.
+
+## Volver al día siguiente
+
+El plan sigue acá, el reclamo en `../claims/` y el árbol de trabajo donde lo dejaste. Lo único que hay
+que reponer es el id: exportá el mismo `CAUCE_RUNNER` —`ops worktree` lo imprime— y `ops context` te
+devuelve tu tarea donde la dejaste. Con otro id, tu propio reclamo se ve ajeno, y `ops claim` te lo dice
+en vez de decidir por vos.

package/template/planning/DONE.md

@@ -1,13 +0,0 @@
-# Done activo
-
-<!--
-## Hito slug — Título
-
-- [x] **slug-de-tarea** (epic: 001) — Resultado
-  acept: comportamiento aceptado
-  done: cambios y comandos de verificación con exit codes
-  qa: comportamiento observado por el camino real
-  tests: C1 → nombre de prueba o comando; C2 → nombre de prueba o comando
-  decisions: decisión no obvia [fuente: ruta/archivo] o [supuesto: motivo verificable]
-  commit: abc1234 feat(scope): subject (repo@branch)
--->

package/template/planning/WIP.md

@@ -1,22 +0,0 @@
-status: IDLE
-
-<!-- Activo:
----
-task: slug
-hito: "Hito slug — Título"
-epic: 001
-phase: Build
-started: YYYY-MM-DD
-service: ruta
-acceptance: "criterio observable"
----
-
-## Plan aprobado
-1. [ ] Paso verificable
-
-## Decisiones tomadas
-- (ninguna)
-
-## Bloqueos
-- (ninguno)
--->