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>
This commit is contained in:
2026-08-27 00:06:01 -06:00
co-authored by Claude Sonnet 5
parent fcee75fe83
commit c06037fa3b
22 changed files with 1682 additions and 1 deletions
+50
View File
@@ -0,0 +1,50 @@
# Runbooks ejecutables
Esta carpeta vive **fuera** de `content/`, así que Zola nunca la construye ni
la publica (confirmado en `zola.toml`: no hay `content_dir` alterno). Es la
razón por la que aquí sí se pueden usar atributos de celda de Runme sin
arriesgar el front matter TOML ni el resaltado de sintaxis que sí usa
`content/manuales/`.
## Cómo abrir un runbook
- **Como notebook (Runme, VS Code):** instale la extensión recomendada en
[`.vscode/extensions.json`](../.vscode/extensions.json) (`stateful.runme`) y
abra el archivo `.md` normalmente; VS Code lo mostrará como notebook.
- **Como Markdown normal:** clic derecho sobre la pestaña → "Reopen Editor
With..." → "Text Editor". Ningún runbook depende de estar en modo notebook
para ser legible o copiable.
- **Por CLI:** `runme run --filename runbooks/<archivo>.md <nombre-de-celda>`.
- **Sin Runme instalado:** copie el bloque de comando y ejecútelo en su
terminal; ninguna celda usa sintaxis que no sea shell/`make`/`clusterlog`
normal.
## Convención de nombres
`kebab-case`, prefijo de proyecto, único en **todo** el repositorio (no sólo
dentro de un archivo): `clusterlog-build`, `clusterlog-validate-local`,
`clusterlog-review-mine`. `clusterlog validate` (ver
`internal/clusterlog/runbooks.go`) falla si dos celdas repiten un nombre.
## Taxonomía de etiquetas
Toda celda debe declarar al menos una etiqueta de cada categoría:
| Categoría | Valores | Obligatoria |
|---|---|---|
| Audiencia | `role-developer`, `role-operator`, `role-reviewer`, `role-owner` | sí |
| Entorno | `env-local`, `env-ci`, `env-staging`, `env-production` | sí |
| Riesgo | `risk-read-only`, `risk-mutating`, `risk-destructive` | sí |
| Ejecución automatizada | `ci-safe`, `manual-only` | no (pero mutuamente excluyente con `risk-mutating`/`risk-destructive`) |
Una celda `risk-mutating` o `risk-destructive` **debe** llevar
`manual-only`, `"interactive":"true"` y `"excludeFromRunAll":true`, y
**no puede** llevar `ci-safe` al mismo tiempo. `clusterlog validate` hace
cumplir esto — no es sólo una convención de estilo.
## Qué no va en una celda
Ver la sección "Runme no contiene lógica de negocio" del ADR
[`docs/adr/0004-runme-sidecar.md`](../docs/adr/0004-runme-sidecar.md). En
resumen: una celda invoca `make`, `./bin/clusterlog` o un script existente; no
reimplementa validación, autorización, rollback ni gestión de secretos.