1# Reglas del repo compartido
2
3Este repo lo trabajan **varios agentes a la vez** (hoy: frente granja/store y frente kernel). Lo de
4aquí abajo no son preferencias de estilo: son las dos formas conocidas de que un agente destruya el
5trabajo de otro sin enterarse. El resto del diseño está en `docs/`.
6
7## 1. Todo `hammer build` va envuelto en `flock`
8
9```sh
10flock work/.farm-build.lock ./target/release/hammer --store ./store build <receta>
11```
12
13Para una tanda, tomar el lock una sola vez y no por receta:
14
15```sh
16flock work/.farm-build.lock bash -c 'for r in ...; do ./target/release/hammer --store ./store build "$r"; done'
17```
18
19**Por qué.** `hammer build` comparte `work/sources/<dep>-<sha>` entre todas las recetas. Dos builds
20concurrentes que compartan una dependencia se pisan el árbol de fuentes: uno hace fetch y lo borra
21mientras el otro lo usa, y **el árbol queda roto para siempre** — reintentar no lo arregla. Medido a
22escala: al invalidar libdrm, ~93 de 205 recetas KDE murieron con `/src/.zwrap/cc is not a full path
23to an existing compiler tool`, que es el wrapper de zig que la receta deja EN EL ÁRBOL, barrido por
24el fetch concurrente de otra receta. Es el **ADR 0012**, sin decidir; hasta que se decida
25(lock por árbol / árbol privado / caché inmutable + copia), serializar es la única mitigación
26correcta. Por eso el worker corre con `JOBS=1`.
27
28`scripts/farm/farm-worker-loop.sh` y `campana-deuda.sh` ya toman **ese mismo fichero de lock**, así
29que usarlo nos serializa con la granja además de entre nosotros. **No está dentro de `hammer build`
30a propósito**: esos scripts lo toman por fuera y hammer se bloquearía contra ellos.
31
32## 2. Nunca `git add -A`
33
34Sólo rutas explícitas. Un `add -A` arrastra al commit los ficheros a medias de otro agente. Commits
35granulares, en español, directo sobre `main`, y `git push` tras cada unidad de trabajo (el `origin`
36empuja a gitea **y** al espejo privado de GitHub; ver `scripts/espejo-setup.sh`).
37
38## 3. Antes de dar un artefacto por presente, mirá que tenga contenido
39
40Un directorio **vacío** en el store no es un artefacto: es un nombre. `Store::has` ya lo rechaza y
41`respaldo-storagebox.sh --listar` los separa a `work/respaldo-vacios.txt`, pero la regla general
42sigue valiendo para cualquier código nuevo — **un ausente falla ruidosamente; un vacío llega hasta
43el final diciendo que todo fue bien**.
44
45## 4. La superficie de la CLI va en INGLÉS; los mensajes, en castellano
46
47Subcomandos, flags y nombres de opciones: **inglés**, sin excepción (`build`, `hash`, `hydrate`,
48`mirror push`, `kernel closure`, `qorpa pull`). Lo que el usuario LEE —ayuda, errores, logs— va en
49castellano, y los nombres propios del proyecto son quechua (`qorpa`, `harkaq`, `yupana`, `arje`).
50
51**Por qué.** Un verbo de CLI es contrato: entra en scripts, cron y runbooks, y renombrarlo después
52rompe llamadores que nadie recuerda. Media superficie en cada idioma obliga a adivinar en cada
53comando nuevo, y ya pasó: el ADR 0015 nació con `traer/crear/correr` y hubo que corregirlo.
54
55⚠ **Deuda conocida, NO barrida todavía:** varios scripts de `scripts/` exponen flags en castellano
56(`--crear`, `--traer`, `--listar`, `--sha`). El barrido es su propia unidad de trabajo — tocarlos de
57paso rompe cron y la granja. Código NUEVO nace en inglés desde hoy.