clusterlogs/README.md

Bitácora Operativa del Clúster (MCPS)

Instancia de 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 — ver docs/adr/0005-motor-instancia.md de ese repositorio para el porqué de la separación.

La solución separa responsabilidades:

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 desde fenandosr/clusterlog, verificando su checksum.

Inicio rápido

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).

./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:

   ./bin/clusterlog --json schema memory
   

3. Prevalida sin escribir:

   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:

   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 y CLAUDE.md.

Flujo de revisión semanal

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

# 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

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 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 y ADR-0004.

Estructura

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: modelo de confianza y despliegue recomendado.
• docs/WEEKLY_REVIEW.md: guion de la reunión semanal.
• 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.

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.