# Bitácora Operativa del Clúster 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 un clúster. 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 | v clusterlog sync ---- genera data/generated/site_state.json | v Zola ---- lectura, navegación, taxonomías y búsqueda ``` ## Qué incluye el MVP - 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. - CLI no interactiva, salida JSON, entrada JSON por archivo o `stdin`, modo `--dry-run` y códigos de salida estables. - Identidad por huella de llave pública SSH y commits Git firmados por SSH con `--commit`. - Detección heurística de secretos antes de escribir contenido. - Estado derivado y reproducible para que Zola siga siendo un sitio estático. ## Requisitos - Go 1.23 o posterior. - Git con soporte de firmas SSH. - OpenSSH/`ssh-keygen` para firmar y verificar commits. - Zola 0.23.3 para construir el sitio. - Acceso al repositorio del tema durante `make theme`, o una copia local indicada con `ZOLA386_SOURCE`. ## Inicio rápido ```bash make theme make build ./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 publicarlo, cambie `base_url` en `zola.toml` y manténgalo detrás de VPN, red privada o autenticación corporativa. ## Registrar al primer administrador La llave pública identifica el registro del administrador. Para una auditoría fuerte, las operaciones posteriores deben usar `--commit` y la rama protegida debe rechazar commits sin firma válida. ```bash ./bin/clusterlog \ --root . \ --ssh-key ~/.ssh/id_ed25519.pub \ admin add \ --id ana \ --name "Ana Torres" \ --email ana@example.org \ --key ~/.ssh/id_ed25519.pub \ --roles owner,admin ``` Configure Git para firmar el primer commit completo: ```bash git init git config user.name "Ana Torres" git config user.email ana@example.org git config gpg.format ssh git config user.signingkey ~/.ssh/id_ed25519 git config commit.gpgsign true git add . git commit -S -m "bootstrap: iniciar bitácora operativa" ``` A partir de ahí: ```bash ./bin/clusterlog --root . --ssh-key ~/.ssh/id_ed25519.pub --commit identity ./bin/clusterlog --root . --ssh-key ~/.ssh/id_ed25519.pub --commit memory create --from-json examples/memory.json ``` `identity` no modifica el repositorio; `--commit` sólo tiene efecto en comandos que escriben archivos. ## 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 ```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 test # pruebas unitarias e integración de la CLI make vet # análisis estático de Go make e2e # flujo completo en una copia temporal make smoke # contratos, sincronización y validación local make validate-local # sin requerir Zola make site # tema + estado + validación completa + sitio make ci # equivalente local de la canalización ``` ## Estructura ```text cmd/clusterlog/ punto de entrada de la CLI internal/clusterlog/ modelo, comandos, validación y proyección content/ Markdown fuente por sección 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 templates/ plantillas locales compatibles con Zola actual static/ ajustes visuales y búsqueda scripts/ preparación del tema y smoke tests docs/ decisiones arquitectónicas y operación ``` ## Documentación clave - [`HOJA_DE_PROYECTO.md`](HOJA_DE_PROYECTO.md): alcance, requisitos, fases y criterios de aceptación. - [`CLI.md`](CLI.md): contrato de comandos, JSON y códigos de salida. - [`SECURITY.md`](SECURITY.md): modelo de confianza y despliegue recomendado. - [`THEME_COMPATIBILITY.md`](THEME_COMPATIBILITY.md): estrategia para `zola.386`. - [`docs/WEEKLY_REVIEW.md`](docs/WEEKLY_REVIEW.md): guion de la reunión semanal. - [`VALIDATION_REPORT.md`](VALIDATION_REPORT.md): pruebas ejecutadas, límites y controles pendientes. - [`RELEASE_NOTES.md`](RELEASE_NOTES.md): alcance de la entrega 0.1.0. ## Estado del prototipo La CLI compila con Go 1.23 y sus pruebas cubren creación por JSON, resolución de identidad, revisión por hash, proyección de tareas y eventos independientes. La construcción de Zola está configurada en la CI incluida. Cuando el registro ya contiene administradores activos, la CI también verifica cada commit del pull request contra `config/allowed_signers`; el scaffold vacío omite esa comprobación durante el bootstrap inicial.