clusterlogs/docs/adr/0004-runme-sidecar.md

ADR-0004: Runme como sidecar de documentación ejecutable

• Estado: aceptada
• Fecha: 2026-08-26

Contexto

Los procedimientos frecuentes de clusterlog (compilar, probar, sincronizar, validar, la revisión semanal) viven como bloques de comando dentro de Markdown que hay que copiar y pegar a mano. Se evaluó integrar Runme (v3.17.4, fijado) para poder abrir esos mismos procedimientos como notebooks ejecutables desde VS Code o su CLI, sin introducir un segundo lugar donde vivan los mismos comandos ni debilitar el modelo de identidad/auditoría existente (huella SSH + commit firmado + clusterlog verify commit).

Decisión

Se integra Runme como una capa opcional y adyacente:

• RUNBOOK.md (raíz) y runbooks/**/*.md son los únicos documentos que llevan atributos de celda Runme.
• Cada celda invoca exclusivamente make, ./bin/clusterlog o un script ya existente en scripts/. Ninguna celda reimplementa validación, autorización, resolución de identidad, rollback o gestión de secretos.
• clusterlog validate (no un script aparte) hace cumplir las reglas de nombres, etiquetas y aislamiento de celdas mutantes — ver internal/clusterlog/runbooks.go.
• La instalación de Runme es opcional y reproducible (scripts/runme-install.sh, checksum verificado); ningún flujo existente (make build, make test, clusterlog sync/validate, zola build) depende de que Runme esté instalado.

Significado de "sidecar"

No es un sidecar de Kubernetes ni un servicio adicional. Es un envoltorio: el humano o agente interactúa con Markdown+Runme, que a su vez llama make, clusterlog o un script — nunca al revés, y nunca con lógica propia.

Ubicación de los runbooks

RUNBOOK.md en la raíz (índice) y runbooks/ como carpeta dedicada, fuera de content/. Se confirmó en zola.toml que Zola no tiene un content_dir alterno: sólo construye desde content/. Poner los runbooks fuera de esa carpeta significa que Zola nunca los toca — cero riesgo de que un atributo de celda {"name":...} rompa el front matter TOML o el resaltado de sintaxis de una página publicada. clusterlog validate además hace cumplir esto activamente: si una celda de Runme aparece dentro de content/, es un error (runme_cell_in_zola_content), no sólo una recomendación.

Relación con content/manuales

content/manuales/ no se toca. Sigue siendo prosa + comandos de ejemplo para lectura humana en el sitio Zola, sin atributos de celda ni ninguna dependencia de Runme. Los runbooks nuevos no son una migración de los manuales existentes: son procedimientos de desarrollo/operación de clusterlog mismo que hoy no existían como documento ejecutable.

Fuente de verdad

Opción elegida de las tres consideradas (sección 4.2 del pedido original): un archivo raíz delgado que enlaza procedimientos canónicos, aplicada así:

• docs/WEEKLY_REVIEW.md conserva la agenda y el criterio de la reunión (prosa) y enlaza a runbooks/weekly-review.md para los comandos ejecutables, en vez de mantener los mismos bloques de shell en dos archivos.
• README.md enlaza RUNBOOK.md y docs/RUNME.md en vez de duplicar ejemplos de comandos.

No se copian bloques de comando manualmente entre dos documentos en ningún punto de esta integración.

Convención de metadatos

Atributos de celda como objeto JSON de una sola línea después del lenguaje del fence: ```sh {"name":"...","tag":"...","interactive":"...", "excludeFromRunAll":true}. clusterlog validate decodifica ese objeto con encoding/json (no confía en una regex para interpretar el contenido; la regex sólo reconoce la forma de la línea de fence).

Taxonomía de etiquetas

Cuatro categorías, tres obligatorias por celda:

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, mutuamente excluyente con riesgo mutante

Modelo de identidad

Tres capas, documentadas en detalle en docs/RUNME.md:

1. Identidad de contenido (Lifecycle Identity / name de Runme): identifica documento y celda, no a quien ejecuta.
2. Evidencia local de sesión (Session Outputs, no habilitados aquí): auxiliar, nunca auditoría canónica.
3. Auditoría canónica de Clusterlog: huella SSH + data/admins.json + commit firmado + clusterlog verify commit, sin cambios.

No se afirma ni se implementa ningún enlace criptográfico entre Runme y un commit. Un futuro clusterlog runbook record queda explícitamente fuera de esta iteración (ver "Trabajo futuro").

Modelo de evidencia

Session Outputs permanecen desactivados por defecto en esta integración. Si se habilitan más adelante, deben quedar fuera de Git, del sitio Zola y de Gists, y tratarse como evidencia auxiliar redactable, nunca como prueba de autoría.

Limitación reconocida: la documentación pública de Runme para v3.17.4 no fija el nombre exacto de archivo de un Session Output (docs.runme.dev/usage/auto-save/ sólo recomienda "agréguelo a .gitignore" sin dar el patrón). Se optó explícitamente por no agregar un glob amplio e inseguro a .gitignore que pudiera ocultar Markdown legítimo. En su lugar, clusterlog validate aplica dos señales concretas (directorio .runme/ versionado; archivos en runbooks/ con "output" en el nombre) como defensa best-effort, documentada como tal.

CI/CD

.gitea/workflows/ci.yml (Gitea Actions, no GitHub Actions — este repo no tiene .github/) gana un job nuevo y separado que no reemplaza test-and-build: instala Runme fijado en v3.17.4 vía scripts/runme-install.sh (checksum verificado), corre make runme-check (reglas de clusterlog validate, obligatorias, más un chequeo blando de compatibilidad de Runme) y make runme-ci (runme run --filename RUNBOOK.md --tag ci-safe --all --skip-prompts). Permisos mínimos (contents: read), DO_NOT_TRACK=true, SCARF_NO_ANALYTICS=true, sin llaves ni acceso a producción.

La CI original de Zola instala herramientas fijadas por curl + tar en vez de una Action de marketplace (ver el paso "Instalar Zola fijado" ya existente); Runme sigue el mismo patrón por consistencia, no por elección nueva.

Seguridad

Ver el nuevo apartado en SECURITY.md. En resumen: una celda Runme equivale a ejecutar comandos locales con los permisos de quien la corre; una etiqueta no es control de acceso, excludeFromRunAll/interactive son defensas adicionales; Runme no lee llaves privadas; Runme Cloud, Gists y runme open expuesto a 0.0.0.0 quedan fuera de alcance.

Alternativas consideradas

1. Celdas dentro de content/manuales/. Descartada: arriesga el front matter TOML y el resaltado de Zola, y mezcla contenido para lectores con contenido para ejecución; no encaja con la opción 1 de fuente única (Markdown único compatible con ambos) porque el pedido de Zola y el de Runme divergen (TOML +++ vs. atributos JSON de celda) sin un beneficio real, dado que runbooks/ fuera de content/ ya resuelve el conflicto sin ese riesgo.
2. Validación en un script Bash aparte en vez de clusterlog validate. Descartada para las reglas estructurales: encajan limpio en el patrón existente de ValidationReport/report.add(...) y ya tenían pruebas unitarias equivalentes para páginas/eventos. Sí se mantiene un script (scripts/runme-check.sh) para el chequeo blando que sólo tiene sentido con el binario real de Runme instalado.
3. Selección de celdas CI-safe con una lista de nombres en el Makefile en vez del flag --tag. Fue el plan inicial, basado en documentación pública de Runme que no mostraba un flag de filtrado por etiqueta. Al instalar el binario real de v3.17.4 se confirmó que runme run --tag sí existe y filtra correctamente (ver docs/RUNME.md). Se adoptó --tag ci-safe --all --skip-prompts porque es la forma más simple que sigue siendo una allowlist explícita por etiqueta de seguridad, no un "correr todo" sin filtro.

Consecuencias

Positivas:

• Los procedimientos de desarrollo se pueden ejecutar como notebook sin perder la posibilidad de copiar/pegar el comando a mano.
• clusterlog validate ahora también protege contra celdas mutantes mal etiquetadas, nombres duplicados y fugas de Runme hacia content/.
• La instalación reproducible con checksum evita depender de latest o de curl | sh.

Negativas / riesgos aceptados:

• El analizador de runbooks es un escáner de líneas, no un parser CommonMark completo; hay casos borde documentados en docs/RUNME.md.
• La detección de Session Outputs es best-effort, no una garantía.
• Dos documentos nuevos (RUNBOOK.md, docs/RUNME.md) que hay que mantener sincronizados con la realidad del Makefile.

Limitaciones

• Zola local (0.22.1) no coincide con la versión que exige README.md y que instala la CI (0.23.3); no se intentó resolver esto en esta iteración.
• No se ejecutó ninguna celda risk-mutating de verdad durante la implementación (por diseño: requieren identidad real y quedan fuera del alcance de una demostración automatizada).
• No existe hoy un enlace criptográfico entre una ejecución de Runme y un commit; quien necesite esa garantía debe seguir el flujo completo de AGENTS.md fuera de Runme.

Trabajo futuro

• Evaluar un comando clusterlog runbook record que capture, con su propio contrato JSON y modelo de amenazas, evidencia de que una celda ci-safe corrió — sólo si el equipo decide que Session Outputs no bastan como evidencia auxiliar.
• Migrar manuales existentes a runbooks ejecutables uno por uno, sólo cuando exista infraestructura real que respalde cada procedimiento (no antes).
• Revisar si vale la pena que runme ls --json exponga etiquetas en una versión futura de Runme, para poder validar la relación entre "celdas etiquetadas ci-safe" y "celdas que runme-ci realmente ejecutó" de forma automatizada en vez de manual.