# Hoja de proyecto: Bitácora Operativa del Clúster **Versión:** 0.1.0 **Fecha base:** 12 de agosto de 2026 **Nombre de trabajo:** Bitácora Operativa del Clúster **CLI:** `clusterlog` **Tipo de producto:** sitio interno estático + CLI de escritura + repositorio Git auditable ## 1. Resumen ejecutivo El equipo de soporte necesita un lugar único para comprender **cómo está construido el clúster, cómo se opera, qué cambió, qué falta por hacer y qué debe revisar el resto del equipo**. La propuesta convierte un repositorio Git en la fuente de verdad y publica una proyección navegable mediante Zola, con la apariencia del tema `zola.386`. La escritura no ocurre en el navegador. Administradores y agentes de programación usan una CLI no interactiva que: - identifica al actor por la huella de su llave pública SSH; - valida el contenido contra contratos predecibles; - crea Markdown y eventos JSON pequeños; - actualiza la proyección que consume Zola; - y, cuando se solicita, deja todo en un commit Git firmado por SSH. La página **Revisión** será la agenda inicial de las reuniones semanales. Muestra las memorias aún no revisadas por todos los administradores requeridos y deja de mostrarlas en cuanto la versión actual obtiene todas las confirmaciones. ## 2. Problema que resuelve Hoy, el conocimiento operativo suele quedar fragmentado entre terminales, chats, tickets, wikis, memoria personal y commits técnicos. Esto produce cinco fallas: 1. No hay una narrativa cronológica de las intervenciones. 2. Los manuales y la arquitectura se desactualizan sin que exista una señal clara. 3. El equipo no sabe qué cambios ya fueron comprendidos por todos. 4. Las tareas y proyectos pierden contexto técnico y tiempo real invertido. 5. Los agentes de IA pueden ayudar a documentar, pero no disponen de un contrato seguro, determinista y atribuible. ## 3. Visión del producto > Después de cada sesión de administración, el equipo debe poder reconstruir qué se intentó, qué se cambió, cómo se validó, cómo se revierte, quién lo ejecutó y quién ya lo revisó, sin depender de la memoria individual. ## 4. Objetivos ### Objetivos del MVP - Centralizar documentación técnica, runbooks, memorias, proyectos y tareas. - Hacer que registrar una memoria tome menos fricción que escribir una nota libre en otro sistema. - Proporcionar a Claude Code y agentes similares un contrato JSON estable y no interactivo. - Atribuir las escrituras a una identidad registrada por llave SSH. - Hacer auditable la aprobación mediante commits SSH firmados. - Construir una cola semanal de revisión reproducible y sin estado oculto en el navegador. - Medir tiempo real de tareas sin introducir una base de datos. - Mantener la solución portable: archivos legibles, Git y un generador estático. ### Objetivos posteriores al MVP - Integración con CI corporativa, SSO, tickets y notificaciones. - Importación de inventario o CMDB. - Reportes de SLO, incidentes, cambios por sistema y deuda operativa. - API remota controlada, sólo cuando el trabajo sin conexión y el modelo Git resulten insuficientes. ### Fuera de alcance del MVP - Edición web multiusuario. - Chat interno, comentarios en tiempo real o presencia. - Almacenamiento de secretos, credenciales o volcados sensibles. - Sustitución de monitoreo, ticketing, CMDB o gestión de incidentes. - Identidad basada únicamente en el comentario textual de una llave. - Firmar en nombre del usuario sin acceso autorizado a su llave privada o agente SSH. ## 5. Usuarios y responsabilidades ### Administrador del clúster Crea memorias, documentación, manuales, tareas y proyectos; registra tiempo; revisa cambios ajenos; conserva su llave privada bajo su control. ### Owner de la bitácora Da de alta administradores, mantiene la política de revisión, protege la rama principal y supervisa la validez de firmas. ### Agente de IA Prepara contenido estructurado en nombre del administrador que inició la sesión. Usa la CLI y su salida JSON; no modifica archivos derivados a mano; no inventa resultados; no expone secretos. ### Lector técnico Consulta el sitio, busca por texto, sistema o etiqueta y usa manuales y memorias como contexto operativo. ## 6. Arquitectura de información | Sección | Propósito | Unidad principal | Cadencia esperada | |---|---|---|---| | Documentación | Explicar estado y diseño vigentes | documento técnico | cuando cambia la arquitectura | | Manuales | Describir procedimientos repetibles | runbook/manual | cuando cambia un procedimiento | | Memorias | Narrar una intervención concreta | entrada cronológica | después de cada sesión o cambio | | Proyectos | Coordinar un resultado de varias tareas | proyecto | semanal/mensual | | Tareas | Registrar trabajo accionable y tiempo | tarea | diaria | | Revisión | Alinear al equipo sobre cambios recientes | proyección de pendientes | semanal | ### Taxonomías comunes - `tags`: tema transversal, por ejemplo `firmware`, `backup`, `seguridad`. - `systems`: componente real afectado, por ejemplo `etcd`, `spine-01`, `ceph`. - `categories`: sección funcional. ### Convención de identificadores - Documentación: `DOC-...` - Manuales: `RUN-...` - Memorias: `MEM-...` - Proyectos: `PRJ-...` - Tareas: `TSK-...` - Eventos: identificadores únicos propios, almacenados en archivos independientes. ## 7. Modelo de datos ### Memoria operativa Campos mínimos o recomendados: - ID, título, resumen y fecha. - autor registrado y huella SSH empleada; - agente que ayudó a redactar, cuando aplique; - sistemas, etiquetas, ticket y nivel de riesgo; - contexto, cambios, comandos redactados, validaciones y reversión; - inicio, fin y duración; - requisito y política de revisión; - conjunto capturado de revisores; - hash SHA-256 de la versión actual, calculado por la CLI. ### Evento de revisión Cada confirmación vive en `data/review-events/.json` e incluye: - memoria; - administrador y huella; - fecha; - hash exacto del contenido revisado; - nota opcional. No existe un booleano mutable `reviewed=true`. La revisión se deriva de eventos válidos para el hash actual. ### Tarea La definición Markdown contiene título, objetivo, prioridad, responsables, proyecto, estimación y fecha. Los cambios de ejecución viven como eventos independientes: - `start`; - `stop`; - `adjust`; - `status`. El tiempo real y el estado efectivo se proyectan al sincronizar. ### Proyecto Incluye objetivo medible, responsables, estado, fecha objetivo, alcance, fuera de alcance, hitos y criterios de éxito. ## 8. Semántica de revisión La revisión debe responder: **“¿qué administradores confirmaron haber comprendido esta versión exacta?”** Reglas: 1. Al crear una memoria se captura el conjunto de revisores aplicable en ese momento. 2. La política puede requerir a todos los activos o a todos excepto el autor. 3. Cada evento registra el hash SHA-256 actual de la memoria. 4. Sólo cuentan eventos cuyo hash coincide con la versión actual. 5. Una edición posterior cambia el hash y vuelve a abrir la memoria automáticamente. 6. Dar de alta a un administrador en el futuro no reabre memorias históricas, porque cada memoria conserva su conjunto capturado. 7. Una memoria sale de `/revision/` cuando no falta ningún revisor. 8. La firma del commit, no la mera presencia de la huella en JSON, aporta la prueba criptográfica de autoría. ## 9. Identidad y confianza ### Resolución de identidad La CLI busca una llave local en este orden general: 1. `--ssh-key`; 2. `CLUSTERLOG_SSH_KEY`; 3. `git config user.signingkey` cuando es una ruta; 4. llaves públicas comunes dentro de `~/.ssh`. Calcula la huella OpenSSH SHA-256 de la llave pública y la compara con `data/admins.json`. ### Límite importante Conocer una llave pública sólo identifica un registro; no demuestra posesión de la privada. Por ello, el flujo de producción debe exigir: - `--commit` en operaciones de escritura; - commits SSH firmados; - `config/allowed_signers` generado desde administradores activos; - verificación en CI; - protección de rama y revisión de cambios en archivos de identidad. ## 10. Requisitos funcionales ### RF-01. Navegación central El sitio debe exponer las seis secciones principales y búsqueda global. **Aceptación:** desde cualquier página se llega a cada sección en un paso. ### RF-02. Creación de memorias por CLI La CLI debe aceptar flags humanos o JSON por archivo/`stdin`. **Aceptación:** `memory create --from-json -` produce una página válida, un ID y una proyección actualizada. ### RF-03. Atribución Toda escritura debe guardar el ID del administrador y la huella resuelta. **Aceptación:** una llave no registrada falla con código de identidad y no escribe archivos. ### RF-04. Revisión por todos La página de revisión debe mostrar faltantes y desaparecer la memoria al completar el conjunto requerido. **Aceptación:** con dos revisores, la entrada sigue visible tras una confirmación y desaparece tras la segunda. ### RF-05. Invalidación por edición Una revisión anterior no debe contar si cambia la memoria. **Aceptación:** modificar el cuerpo y ejecutar `sync` vuelve a mostrar la entrada. ### RF-06. Tareas y tiempo Debe ser posible crear, iniciar, detener, ajustar y completar una tarea. **Aceptación:** el tiempo real es la suma reproducible de eventos y no puede ser negativo. ### RF-07. Proyectos Debe ser posible crear y listar proyectos con objetivo y estado. **Aceptación:** las tareas pueden enlazar un proyecto existente y la validación rechaza referencias inexistentes. ### RF-08. Operación por agentes Debe existir salida JSON estable, esquemas JSON y `--dry-run`. **Aceptación:** un agente puede descubrir el esquema, validar y escribir sin prompts ni parsing de texto humano. ### RF-09. Validación La CLI debe revisar estructura, referencias, eventos, firmas autorizables, secretos probables, proyección y Zola. **Aceptación:** `validate --require-zola` falla ante cualquier error bloqueante. ### RF-10. Auditoría Git Una operación con `--commit` debe añadir sólo los archivos que creó o modificó y producir un commit SSH firmado. **Aceptación:** `verify commit ` confirma la firma contra `config/allowed_signers`. ## 11. Requisitos no funcionales - **Portabilidad:** Markdown, JSON y Git deben seguir siendo legibles sin la CLI. - **Determinismo:** la misma fuente genera la misma proyección, salvo la marca informativa `generated_at` controlada por la sincronización. - **Concurrencia Git:** cada revisión y evento de tarea ocupa un archivo distinto para minimizar conflictos. - **Seguridad:** no almacenar secretos; sitio no indexable y desplegado en red privada. - **Accesibilidad:** navegación semántica, uso por teclado y contenido legible sin JavaScript salvo la búsqueda. - **Mantenibilidad:** plantillas locales separadas del tema visual fijado. - **Observabilidad:** errores con `kind`, detalles y código de salida estable. - **Recuperación:** toda proyección puede eliminarse y regenerarse desde la fuente. ## 12. Diseño de la CLI Forma general: ```text clusterlog [--root DIR] [--json] [--ssh-key PATH] [--commit] [--dry-run] COMANDO ``` Principios: - flags globales antes del comando; - sin prompts interactivos; - operaciones de creación atómicas; - `stdin` con `--from-json -` o `--body-file -`; - respuesta JSON envuelta en `{ok, command, data, warnings}`; - errores JSON con `kind`, `message`, `details` y código de proceso; - no sobrescribir eventos existentes; - comandos idempotentes cuando existe un estado equivalente, por ejemplo revisar dos veces el mismo hash. La referencia exhaustiva está en `CLI.md`. ## 13. Arquitectura técnica ```text ┌───────────────────────────────┐ │ Humano / Claude Code / agente │ └───────────────┬───────────────┘ │ JSON o flags v ┌───────────────────────────────┐ │ clusterlog (Go) │ │ identidad · validación · Git │ └───────┬──────────────┬────────┘ │ │ │ Markdown │ eventos JSON inmutables v v ┌───────────────────────────────────────────────┐ │ Repositorio Git │ │ content/ · data/ · config/allowed_signers │ └───────────────────┬───────────────────────────┘ │ sync v ┌───────────────────────────────────────────────┐ │ data/generated/site_state.json │ │ cola · métricas · tareas · proyectos · memoria│ └───────────────────┬───────────────────────────┘ │ load_data v ┌───────────────────────────────────────────────┐ │ Zola + recursos visuales de zola.386 │ └───────────────────────────────────────────────┘ ``` ### Decisión sobre estado compartido No se usa `localStorage`, una cookie ni un formulario estático para las revisiones. Esos mecanismos no representan un consenso compartido ni son auditables. El estado se conserva en Git y Zola sólo lo presenta. ### Decisión sobre el tema Se fijan Sass y archivos estáticos de `zola.386` a una revisión concreta. Las plantillas son locales, porque el tema original precede a cambios mayores de Zola/Tera y el proyecto necesita estructuras específicas para revisión, tareas y proyectos. ## 14. Alcance del MVP entregado ### Incluido - estructura Zola y navegación; - tema visual preparado mediante script; - CLI Go funcional; - contratos JSON y ejemplos; - registro de administradores; - memoria/revisión por hash; - tareas y eventos de tiempo; - proyectos; - proyección para el sitio; - validación y escaneo de secretos probables; - commits y verificación SSH; - pruebas Go; - CI para Zola 0.23.3; - documentación de seguridad y operación. ### Pendiente para producción - reemplazar dominio de ejemplo; - decidir hosting interno y autenticación; - configurar protección de rama y verificación obligatoria de firmas; - poblar administradores reales; - revisar taxonomía de sistemas; - probar la canalización en el repositorio corporativo; - definir retención y clasificación de información; - integrar respaldos del repositorio. ## 15. Fases recomendadas ### Fase 0 — Alineación y seguridad - Aprobar nombres, secciones y política de revisión. - Definir qué información está prohibida. - Seleccionar repositorio y hosting interno. - Registrar owners iniciales. **Salida:** decisiones aprobadas y threat model aceptado. ### Fase 1 — Piloto técnico - Desplegar el prototipo. - Incorporar de dos a cuatro administradores. - Importar cinco manuales y diez memorias recientes. - Ejecutar dos reuniones semanales usando `/revision/`. **Salida:** retroalimentación sobre fricción, campos y cola. ### Fase 2 — Adopción operativa - Añadir plantilla a las instrucciones de Claude Code. - Exigir `validate` y firmas en pull requests. - Migrar proyectos y tareas activas. - Establecer responsables de calidad documental. **Salida:** bitácora como flujo normal, no como actividad extraordinaria. ### Fase 3 — Integraciones - Enlaces automáticos a tickets. - Notificaciones de revisión. - Métricas y reportes de mantenimiento. - Evaluar una API sólo con casos concretos que Git no resuelva. ## 16. Riesgos y mitigaciones | Riesgo | Consecuencia | Mitigación | |---|---|---| | El agente incluye un secreto | exposición en Git y sitio | contrato explícito, escáner heurístico, revisión humana y herramientas corporativas de secret scanning | | Se suplanta una huella en un JSON | falsa atribución aparente | exigir commit SSH firmado y verificarlo en CI | | Dos personas editan el mismo estado | conflictos de merge | un archivo por evento y Markdown por entidad | | Una memoria cambia después de revisarse | consenso obsoleto | hash de contenido en cada revisión | | Un nuevo admin reabre todo el histórico | cola inmanejable | captura de revisores por memoria | | El tema deja de compilar | bloqueo de publicación | revisión fijada, plantillas locales y build en CI | | El sitio se expone a Internet | fuga de conocimiento operativo | VPN/SSO, `robots.txt`, `noindex`, mínimo privilegio | | La documentación se vuelve burocrática | baja adopción | JSON preparado por agente, campos mínimos y plantillas breves | | Git crece con muchos eventos | mantenimiento | eventos pequeños, política de archivo posterior y métricas reales antes de rediseñar | ## 17. Métricas de éxito del piloto - Porcentaje de cambios relevantes con memoria dentro de 24 horas. - Tiempo mediano para registrar una memoria. - Porcentaje de memorias revisadas antes de la siguiente reunión. - Antigüedad máxima de un pendiente de revisión. - Número de manuales actualizados a partir de hallazgos en memorias. - Diferencia entre tiempo estimado y real por categoría de tareas. - Errores de validación o secretos bloqueados antes de llegar a la rama principal. Las métricas deben usarse para mejorar el sistema, no para evaluar individualmente el desempeño sin contexto. ## 18. Criterios de aceptación del MVP El MVP se considera aceptado cuando: 1. La CLI compila y todas las pruebas automatizadas pasan. 2. Zola construye el sitio con el tema preparado y las plantillas locales. 3. Un owner puede registrar a un segundo administrador. 4. Una memoria creada por JSON aparece en Memorias y Revisión. 5. Cada administrador puede revisarla desde su propia llave. 6. La memoria desaparece al completar el conjunto de revisores. 7. Editar la memoria vuelve a abrir su revisión. 8. Una tarea registra tiempo y puede completarse sin producir minutos negativos. 9. Una tarea puede enlazarse a un proyecto existente. 10. La validación detecta referencias inválidas, temporizadores inconsistentes y secretos probables. 11. Los commits creados con `--commit` se verifican contra `allowed_signers`. 12. La rama principal exige CI y firmas según la política del repositorio. 13. El sitio está accesible sólo en el entorno interno acordado. ## 19. Definición de terminado para cada cambio Un cambio está terminado cuando: - tiene pruebas o una justificación explícita de por qué no aplican; - no introduce secretos ni datos personales innecesarios; - actualiza esquema, documentación y ejemplo cuando cambia un contrato; - ejecuta `go test ./...`, `go vet ./...`, `clusterlog sync --check` y `clusterlog validate`; - construye con Zola en CI; - conserva compatibilidad de salida JSON o incrementa versión con migración; - queda en un commit firmado y revisable. ## 20. Backlog inmediato priorizado ### P0 — antes del piloto - Configurar dominio interno, hosting y acceso. - Ejecutar CI en el repositorio real. - Registrar owners y política de firmas. - Revisar patrones del escáner de secretos con ejemplos del entorno. - Crear los primeros manuales críticos: acceso, respaldo, restauración y escalamiento. ### P1 — durante el piloto - Añadir edición controlada de tareas y proyectos mediante eventos o comandos específicos. - Añadir desactivación/rotación de llaves de administradores. - Añadir verificación de firma para un rango de commits en CI. - Generar una vista “mis pendientes”. - Incorporar relaciones entre memorias y documentación que debe actualizarse. ### P2 — después de validar adopción - Notificaciones de revisión pendientes. - Importación de tickets. - Reportes de actividad por sistema y riesgo. - Archivado por periodo y política de retención. - API o servicio de escritura sólo si los flujos Git resultan insuficientes. ## 21. Preguntas de gobierno que el equipo debe cerrar - ¿El autor debe revisar su propia memoria o se excluye por defecto? - ¿Qué riesgo exige revisión síncrona antes del cambio y cuál permite revisión posterior? - ¿Cuánto tiempo puede permanecer una memoria pendiente? - ¿Quién puede registrar, desactivar o rotar llaves? - ¿Qué datos de infraestructura están permitidos en el sitio? - ¿Qué sistema conserva el ticket canónico y cuál sólo enlaza? - ¿Cuándo una memoria obliga a actualizar un manual o documento de arquitectura? - ¿Qué estados de proyecto y tarea necesita realmente el equipo? Estas decisiones son configuración y proceso; no requieren convertir el MVP en una aplicación con base de datos.