feat(runme): integrar Runme como sidecar de documentación ejecutable

Agrega RUNBOOK.md y runbooks/ (fuera de content/, para no interferir con la publicación de Zola), con reglas de nombres/etiquetas/aislamiento de celdas mutantes verificadas por clusterlog validate. Instalación pinneada a v3.17.4 con checksum verificado (scripts/runme-install.sh), un job de CI separado (.gitea/workflows/ci.yml) que sólo corre celdas ci-safe, y la decisión documentada en docs/adr/0004-runme-sidecar.md y docs/RUNME.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-27 00:06:01 -06:00
parent fcee75fe83
commit c06037fa3b
22 changed files with 1682 additions and 1 deletions
@@ -0,0 +1,89 @@
+# Ciclo de desarrollo de clusterlog
+
+Propósito: correr el mismo ciclo que `AGENTS.md` pide "antes de entregar",
+como notebook en vez de copiar/pegar bloques sueltos. Todas las celdas de
+este documento envuelven targets existentes de `Makefile`; ninguna reimplementa
+lo que ya hace `go test`, `go vet` o `clusterlog`.
+
+## Prerrequisitos
+
+- Go 1.23+, Git con firmas SSH.
+- Para las celdas con Zola: binario `zola` en `PATH` (opcional; las celdas de
+  `validate`/`sync` no lo requieren).
+
+## Formato
+
+```sh {"name":"clusterlog-gofmt-check","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+test -z "$(gofmt -l cmd internal)"
+```
+
+## Pruebas y análisis estático
+
+```sh {"name":"clusterlog-vet","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+go vet ./...
+```
+
+```sh {"name":"clusterlog-test-race","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+go test -race ./...
+```
+
+## Compilar y proyectar
+
+```sh {"name":"clusterlog-dev-build","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+make build
+```
+
+```sh {"name":"clusterlog-dev-sync","tag":"role-developer,env-local,risk-mutating,manual-only","interactive":"true","excludeFromRunAll":true}
+# Escribe data/generated/site_state.json. Revise el diff antes de confirmar
+# cualquier commit que incluya ese archivo regenerado.
+make sync
+git diff --stat -- data/generated/site_state.json
+```
+
+### Prerrequisitos de `clusterlog-dev-sync`
+
+- Haber corrido `clusterlog-dev-build` en esta sesión (o tener `bin/clusterlog`
+  ya compilado).
+
+### Validación posterior
+
+```sh {"name":"clusterlog-dev-sync-check","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+make sync-check
+```
+
+### Rollback
+
+`data/generated/site_state.json` es 100% regenerable desde el contenido
+fuente (`content/`, `data/admins.json`, `data/*-events/`). Si `make sync`
+produjo un diff no deseado, descarte el archivo con
+`git checkout -- data/generated/site_state.json` y no lo incluya en el commit.
+
+## Validar
+
+```sh {"name":"clusterlog-dev-validate-local","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+make validate-local
+```
+
+## Flujo completo local (equivalente a CI, sin Zola)
+
+```sh {"name":"clusterlog-dev-smoke","tag":"role-developer,env-local,risk-read-only,ci-safe","interactive":"false"}
+make build
+./bin/clusterlog --root . sync --check
+./bin/clusterlog --root . validate --skip-zola
+./scripts/smoke.sh
+```
+
+## Registro en Clusterlog
+
+Ninguna celda de este runbook crea memorias, tareas ni commits. Si el
+trabajo de la sesión amerita una memoria, hágalo con el flujo normal descrito
+en `AGENTS.md` (`clusterlog memory create --from-json`, con `--dry-run` antes
+de `--commit`) — fuera de Runme, con su propia llave.
+
+## Limitaciones
+
+- `clusterlog-dev-sync` está marcado `manual-only` a propósito: regenera un
+  archivo versionado y su diff debe revisarse antes de confirmarlo.
+- Este runbook no incluye `make site`/`zola build`: ver
+  [`RUNBOOK.md`](../RUNBOOK.md#comprobaciones-rápidas) para por qué esa celda
+  vive ahí y no se duplica aquí.