clusterlogs/README.md

# Bitácora Operativa del Clúster (MCPS)

Instancia de [`clusterlog`](https://github.com/fenandosr/clusterlog): sitio
interno y CLI auditable para conservar en un solo lugar la documentación,
los manuales, las memorias de cambio, los proyectos, las tareas y la agenda
de revisión semanal del equipo que administra el clúster MCPS.

Este repositorio contiene únicamente **datos de este deployment**
(`content/`, `data/`, `config/`, `zola.toml`, `.clusterlog-version`). El
código de la CLI, las plantillas y el mecanismo de tema viven en el motor:
[fenandosr/clusterlog](https://github.com/fenandosr/clusterlog) — ver
`docs/adr/0005-motor-instancia.md` de ese repositorio para el porqué de la
separación.

La solución separa responsabilidades:

```text
administrador o agente IA
          |
          v
     clusterlog CLI  ---- identifica por huella SSH
          |          ---- valida contratos y secretos probables
          |          ---- escribe Markdown/eventos JSON
          |          ---- opcionalmente crea commit SSH firmado
          v
     repositorio Git ---- fuente de verdad y auditoría (esta instancia)
          |
          v
     clusterlog sync ---- genera data/generated/site_state.json
          |
          v
        Zola         ---- lectura, navegación, taxonomías y búsqueda
```

## Qué incluye

- Secciones de **Documentación**, **Manuales**, **Memorias**, **Proyectos**, **Tareas** y **Revisión**.
- Memorias operativas con autor, huella SSH, riesgo, sistemas, etiquetas, ticket, duración, validación y reversión.
- Cola de revisión por administrador. Una memoria desaparece cuando todos los revisores capturados para esa entrada la aprobaron.
- Invalidación automática de revisiones cuando cambia el contenido de una memoria.
- Tareas con estimación, fecha objetivo, responsables, estado y tiempo real mediante eventos `start`, `stop` y `adjust`.
- Proyectos con objetivo, responsables, alcance, hitos, criterio de éxito y estado.
- Identidad por huella de llave pública SSH y commits Git firmados por SSH con `--commit`.

## Requisitos

- Git con soporte de firmas SSH.
- OpenSSH/`ssh-keygen` para firmar y verificar commits.
- Zola 0.23.3 para construir el sitio.
- **No requiere Go ni un checkout del motor**: `make build`/`make templates` descargan el binario y las plantillas fijadas en [`.clusterlog-version`](.clusterlog-version) desde `fenandosr/clusterlog`, verificando su checksum.

## Inicio rápido

```bash
make theme       # tema zola.386 (repositorio externo, pinneado)
make templates   # plantillas del motor, versión fijada
make build       # binario clusterlog, versión fijada
./bin/clusterlog --root . sync
./bin/clusterlog --root . validate --skip-zola
zola serve
```

El sitio queda disponible en la dirección que muestre Zola. Antes de publicar un cambio a `base_url`/`zola.toml`, manténgalo detrás de VPN, red privada o autenticación corporativa.

## Registrar un administrador nuevo

Sólo un `owner` activo puede hacerlo (ver `content/manuales/primer-administrador.md` para el procedimiento completo, incluido el alta del segundo administrador).

```bash
./bin/clusterlog \
  --root . \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --commit \
  admin add \
  --id ana \
  --name "Ana Torres" \
  --email ana@example.org \
  --key ~/.ssh/id_ed25519.pub \
  --roles admin
```

## Flujo para Claude Code u otro agente

1. El agente recopila y redacta los hechos de la sesión, sin incluir credenciales ni valores sensibles.
2. Consulta el contrato:

   ```bash
   ./bin/clusterlog --json schema memory
   ```

3. Prevalida sin escribir:

   ```bash
   cat session-memory.json | ./bin/clusterlog \
     --root . --json --dry-run \
     --ssh-key ~/.ssh/id_ed25519.pub \
     memory create --from-json -
   ```

4. Escribe y firma una unidad atómica:

   ```bash
   cat session-memory.json | ./bin/clusterlog \
     --root . --json --commit \
     --ssh-key ~/.ssh/id_ed25519.pub \
     memory create --from-json -
   ```

5. El agente devuelve al humano el `entry_id`, la ruta y el SHA del commit; nunca afirma que la firma fue válida sin comprobar la salida.

Las instrucciones completas para agentes están en [`AGENTS.md`](AGENTS.md) y [`CLAUDE.md`](CLAUDE.md).

## Flujo de revisión semanal

Versión ejecutable (Runme) en [`runbooks/weekly-review.md`](runbooks/weekly-review.md); agenda y criterio en [`docs/WEEKLY_REVIEW.md`](docs/WEEKLY_REVIEW.md):

```bash
# Ver sólo las memorias que le faltan al administrador actual
./bin/clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub review list --mine

# Marcar la versión actual como revisada y crear un commit firmado
./bin/clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  review mark MEM-... --note "Revisado en reunión semanal"

# Confirmar la firma del commit actual
./bin/clusterlog --root . verify commit HEAD
```

La página `/revision/` contiene la cola pendiente y, como apoyo a la reunión, las tareas abiertas y los proyectos planeados, activos o bloqueados.

## Comandos de calidad

```bash
make sync-check      # comprueba que la proyección está actualizada
make validate-local  # valida sin requerir Zola
make site            # tema + plantillas + estado + validación completa + sitio
make smoke           # contratos, sincronización y validación local
make ci              # equivalente local de la canalización
```

## Documentación ejecutable (Runme)

Los procedimientos frecuentes también existen como notebooks ejecutables,
sin reemplazar ningún comando canónico: [`RUNBOOK.md`](RUNBOOK.md) es el
punto de entrada. Requiere Runme `v3.17.4` (`make runme-install`) sólo si se
quiere abrir como notebook o correr por CLI; cada celda es, además, un
bloque de shell normal que sigue funcionando copiado a mano. Modelo de
identidad, limitaciones y la decisión completa viven en el motor:
[`docs/RUNME.md`](https://github.com/fenandosr/clusterlog/blob/main/docs/RUNME.md)
y
[ADR-0004](https://github.com/fenandosr/clusterlog/blob/main/docs/adr/0004-runme-sidecar.md).

## Estructura

```text
content/                 Markdown fuente por sección (memorias, manuales, ...)
data/admins.json         registro de administradores y política
data/review-events/      un archivo por revisión
data/task-events/        un archivo por evento de tiempo/estado
data/generated/          proyección regenerable para Zola
config/allowed_signers   firmantes SSH autorizados (generado junto a admins.json)
templates/, themes/      descargados por make templates/make theme — no versionados
static/                  ajustes visuales y búsqueda propios de esta instancia
scripts/                 fetch del motor, tema, smoke test, verificación de firmas
runbooks/, RUNBOOK.md    documentación ejecutable de esta instancia
docs/                    guion de la reunión semanal
.clusterlog-version      versión fijada del motor que usa esta instancia
```

## Documentación clave

- [`SECURITY.md`](SECURITY.md): modelo de confianza y despliegue recomendado.
- [`docs/WEEKLY_REVIEW.md`](docs/WEEKLY_REVIEW.md): guion de la reunión semanal.
- [`content/manuales/`](content/manuales/): procedimientos operativos de esta instancia (acceso SSH, correo, Caddy, alta de administradores...).
- Documentación del motor (CLI, esquemas, ADRs, `bootstrap-instance`, Runme): [fenandosr/clusterlog](https://github.com/fenandosr/clusterlog).

## Estado

Instancia activa del clúster MCPS. La CI (`.gitea/workflows/ci.yml`) descarga el binario y las plantillas del motor por versión fijada, sincroniza y valida el contenido, construye con Zola y publica en `clusterlog.mcps-epcm.org` al hacer push a `main`. También verifica cada commit del pull request contra `config/allowed_signers`.