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:
@@ -0,0 +1,120 @@
|
||||
# Reunión semanal de revisión — versión ejecutable
|
||||
|
||||
Este runbook es el complemento ejecutable de
|
||||
[`docs/WEEKLY_REVIEW.md`](../docs/WEEKLY_REVIEW.md), que conserva la agenda y
|
||||
el criterio de la reunión. Los comandos de preparación y cierre viven aquí
|
||||
una sola vez; `docs/WEEKLY_REVIEW.md` enlaza a este archivo en vez de repetir
|
||||
los bloques de shell.
|
||||
|
||||
## Propósito
|
||||
|
||||
Preparar y cerrar la reunión semanal sin copiar comandos a mano.
|
||||
|
||||
## Propietario
|
||||
|
||||
Cada administrador ejecuta su propia preparación con su propia llave.
|
||||
|
||||
## Audiencia
|
||||
|
||||
`role-reviewer`, `role-owner`.
|
||||
|
||||
## Entornos permitidos
|
||||
|
||||
`env-local` únicamente. Ningún comando de este runbook debe correr en CI:
|
||||
todos requieren identidad SSH personal o mutan la cola de revisión.
|
||||
|
||||
## Clasificación de riesgo
|
||||
|
||||
Preparación: `risk-read-only`. Marcar una revisión: `risk-mutating`.
|
||||
|
||||
## Prerrequisitos
|
||||
|
||||
- `CLUSTERLOG_SSH_KEY` apuntando a su llave pública registrada.
|
||||
- Haber leído las memorias pendientes antes de marcarlas.
|
||||
|
||||
## Variables requeridas
|
||||
|
||||
- `CLUSTERLOG_SSH_KEY`: ruta a su llave pública.
|
||||
- `MEM_ID`: el `entry_id` exacto de la memoria que va a marcar (por ejemplo
|
||||
`MEM-20260825-ABC123`), sólo para la celda de cierre.
|
||||
|
||||
## Preflight
|
||||
|
||||
```sh {"name":"weekly-review-identity","tag":"role-reviewer,env-local,risk-read-only","interactive":"false"}
|
||||
: "${CLUSTERLOG_SSH_KEY:?defina CLUSTERLOG_SSH_KEY}"
|
||||
./bin/clusterlog --root . --json --ssh-key "$CLUSTERLOG_SSH_KEY" identity
|
||||
```
|
||||
|
||||
## Procedimiento
|
||||
|
||||
### 1. Preparación individual
|
||||
|
||||
```sh {"name":"weekly-review-pending","tag":"role-reviewer,env-local,risk-read-only","interactive":"false"}
|
||||
: "${CLUSTERLOG_SSH_KEY:?defina CLUSTERLOG_SSH_KEY}"
|
||||
./bin/clusterlog --root . --json --ssh-key "$CLUSTERLOG_SSH_KEY" review list --mine
|
||||
```
|
||||
|
||||
```sh {"name":"weekly-review-my-tasks","tag":"role-reviewer,env-local,risk-read-only","interactive":"false"}
|
||||
: "${CLUSTERLOG_SSH_KEY:?defina CLUSTERLOG_SSH_KEY}"
|
||||
./bin/clusterlog --root . --json --ssh-key "$CLUSTERLOG_SSH_KEY" task list --mine
|
||||
```
|
||||
|
||||
### 2. Marcar una memoria como revisada (durante o después de la reunión)
|
||||
|
||||
```sh {"name":"weekly-review-mark","tag":"role-reviewer,env-production,risk-mutating,manual-only","interactive":"true","excludeFromRunAll":true}
|
||||
: "${CLUSTERLOG_SSH_KEY:?defina CLUSTERLOG_SSH_KEY}"
|
||||
: "${MEM_ID:?defina MEM_ID con el entry_id exacto de la memoria, por ejemplo MEM-20260825-ABC123}"
|
||||
./bin/clusterlog --root . --json --commit --ssh-key "$CLUSTERLOG_SSH_KEY" \
|
||||
review mark "$MEM_ID" --note "Revisado en reunión semanal"
|
||||
```
|
||||
|
||||
Prerrequisito adicional de esta celda: haber leído y entendido la memoria
|
||||
completa, no sólo su título. `env-production` porque un `--commit` exitoso
|
||||
queda en el historial de Git compartido — no es una operación de laboratorio.
|
||||
|
||||
### 3. Cierre
|
||||
|
||||
```sh {"name":"weekly-review-close-check","tag":"role-owner,env-local,risk-read-only,ci-safe","interactive":"false"}
|
||||
make sync-check
|
||||
```
|
||||
|
||||
```sh {"name":"weekly-review-close-validate","tag":"role-owner,env-local,risk-read-only,ci-safe","interactive":"false"}
|
||||
make validate-local
|
||||
```
|
||||
|
||||
```sh {"name":"weekly-review-close-verify","tag":"role-owner,env-local,risk-read-only,ci-safe","interactive":"false"}
|
||||
./bin/clusterlog --root . verify commit HEAD
|
||||
```
|
||||
|
||||
## Validación
|
||||
|
||||
`review list --mine` debe quedar vacío (o con causa y fecha de seguimiento
|
||||
documentada aparte, según `docs/WEEKLY_REVIEW.md`).
|
||||
|
||||
## Rollback
|
||||
|
||||
`review mark` no tiene reversión directa: agrega un evento inmutable en
|
||||
`data/review-events/`. Si se marcó por error, no se edita el evento; se
|
||||
documenta el error en la siguiente memoria y se decide en equipo si se
|
||||
requiere una excepción de política (ver "Preguntas de gobierno" en
|
||||
`HOJA_DE_PROYECTO.md`).
|
||||
|
||||
## Registro en Clusterlog
|
||||
|
||||
`review mark --commit` ya deja su propio commit firmado; no hace falta una
|
||||
memoria adicional sólo por marcar una revisión.
|
||||
|
||||
## Evidencia
|
||||
|
||||
Salida JSON de `review mark` (contiene el hash de contenido revisado) y el
|
||||
SHA del commit que produce.
|
||||
|
||||
## Referencias
|
||||
|
||||
- [`docs/WEEKLY_REVIEW.md`](../docs/WEEKLY_REVIEW.md)
|
||||
- [`CLI.md`](../CLI.md), sección 7 (Revisión).
|
||||
|
||||
## Limitaciones
|
||||
|
||||
Ninguna celda de este runbook es `ci-safe`: todas requieren una llave SSH
|
||||
personal o mutan estado compartido. Esto es intencional, no una omisión.
|
||||
Reference in New Issue
Block a user