bootstrap: iniciar bitácora operativa
This commit is contained in:
@@ -0,0 +1,368 @@
|
||||
# Referencia de `clusterlog`
|
||||
|
||||
## 1. Forma general
|
||||
|
||||
```text
|
||||
clusterlog [opciones globales] <comando> [opciones del comando]
|
||||
```
|
||||
|
||||
Las opciones globales deben colocarse **antes** del comando.
|
||||
|
||||
| Opción | Efecto |
|
||||
|---|---|
|
||||
| `--root DIR` | raíz del repositorio; si se omite, la CLI busca el proyecto desde el directorio actual |
|
||||
| `--json` | salida estructurada y estable para agentes |
|
||||
| `--ssh-key PATH` | llave pública o ruta base usada para resolver identidad y firma |
|
||||
| `--commit` | crea un commit Git SSH firmado con sólo los archivos de la operación |
|
||||
| `--dry-run` | valida y calcula el resultado sin escribir |
|
||||
|
||||
También puede definirse `CLUSTERLOG_SSH_KEY`.
|
||||
|
||||
## 2. Contrato JSON
|
||||
|
||||
Éxito:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "memory.create",
|
||||
"data": {},
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
Error:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": {
|
||||
"kind": "identity_not_found",
|
||||
"message": "ninguna llave SSH local coincide con un administrador activo",
|
||||
"details": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Un agente debe usar el código del proceso como decisión primaria y `error.kind` para tratamiento específico. No debe inferir éxito por texto parcial.
|
||||
|
||||
## 3. Códigos de salida
|
||||
|
||||
| Código | Significado |
|
||||
|---:|---|
|
||||
| `0` | éxito |
|
||||
| `2` | uso, flags o entrada inválida |
|
||||
| `3` | identidad no encontrada o no autorizada |
|
||||
| `4` | validación, firma o contenido inválido |
|
||||
| `5` | conflicto de estado |
|
||||
| `6` | operación Git fallida |
|
||||
| `10` | error interno no clasificado |
|
||||
|
||||
## 4. Identidad
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub identity
|
||||
```
|
||||
|
||||
La respuesta incluye el administrador, la huella, la ruta pública y la ruta que Git intentará usar para firmar. No prueba posesión hasta que exista una firma válida.
|
||||
|
||||
## 5. Administradores
|
||||
|
||||
### Agregar
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Reglas:
|
||||
|
||||
- El primer administrador obtiene `owner` aunque no se incluya explícitamente.
|
||||
- Después del primero, sólo un `owner` puede agregar administradores.
|
||||
- No se aceptan IDs, correos o huellas duplicados.
|
||||
- `data/admins.json` y `config/allowed_signers` se actualizan juntos.
|
||||
|
||||
### Listar
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json admin list
|
||||
clusterlog --root . --json admin list --active
|
||||
```
|
||||
|
||||
## 6. Memorias
|
||||
|
||||
### Consultar esquema
|
||||
|
||||
```bash
|
||||
clusterlog --json schema memory
|
||||
```
|
||||
|
||||
### Crear por JSON
|
||||
|
||||
```bash
|
||||
cat examples/memory.json | clusterlog \
|
||||
--root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
memory create --from-json -
|
||||
```
|
||||
|
||||
### Crear por flags
|
||||
|
||||
```bash
|
||||
clusterlog --root . --commit --ssh-key ~/.ssh/id_ed25519.pub memory create \
|
||||
--title "Rotar certificado del API" \
|
||||
--description "Renovación programada y comprobación de clientes" \
|
||||
--tags tls,certificados \
|
||||
--systems kube-apiserver \
|
||||
--risk medium \
|
||||
--ticket CHG-1042 \
|
||||
--duration 45m \
|
||||
--agent claude-code \
|
||||
--body-file memoria.md
|
||||
```
|
||||
|
||||
Opciones específicas:
|
||||
|
||||
- `--title`
|
||||
- `--description`
|
||||
- `--tags`
|
||||
- `--systems`
|
||||
- `--risk low|medium|high|critical`
|
||||
- `--ticket`
|
||||
- `--review` (por defecto `true`)
|
||||
- `--review-policy all-active|all-active-except-author`
|
||||
- `--duration` en minutos, `90m` o `2h`
|
||||
- `--agent`
|
||||
- `--body-file ARCHIVO|-`
|
||||
- `--from-json ARCHIVO|-`
|
||||
|
||||
Cuando se combinan JSON y flags, los flags que se proporcionen explícitamente tienen precedencia.
|
||||
|
||||
## 7. Revisión
|
||||
|
||||
### Listar pendientes
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json review list
|
||||
clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub review list --mine
|
||||
```
|
||||
|
||||
`--mine` requiere identidad y devuelve sólo memorias cuyo conjunto pendiente contiene al administrador actual.
|
||||
|
||||
### Marcar la versión actual
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
review mark MEM-20260812-... --note "Revisado; sin objeciones"
|
||||
```
|
||||
|
||||
El evento guarda el SHA-256 del contenido actual. Repetir el comando sobre el mismo hash es idempotente; editar la memoria hace que el evento anterior deje de contar.
|
||||
|
||||
## 8. Tareas
|
||||
|
||||
### Crear
|
||||
|
||||
```bash
|
||||
cat examples/task.json | clusterlog \
|
||||
--root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task create --from-json -
|
||||
```
|
||||
|
||||
Flags disponibles:
|
||||
|
||||
- `--title`, `--description`
|
||||
- `--project PRJ-...`
|
||||
- `--priority low|medium|high|urgent`
|
||||
- `--assignees ana,luis`
|
||||
- `--estimate 120m`
|
||||
- `--due YYYY-MM-DD`
|
||||
- `--tags`, `--systems`
|
||||
- `--objective`
|
||||
- `--acceptance` separado por comas
|
||||
- `--notes`
|
||||
- `--body-file ARCHIVO|-`
|
||||
- `--from-json ARCHIVO|-`
|
||||
|
||||
### Iniciar y detener tiempo
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task start TSK-... --note "Diagnóstico inicial"
|
||||
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task stop TSK-... --note "Prueba completada"
|
||||
```
|
||||
|
||||
Un administrador sólo puede mantener un temporizador activo. Los eventos se ordenan por fecha y tipo para producir un total reproducible.
|
||||
|
||||
### Ajustar tiempo
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task adjust TSK-... --minutes 20 --note "Trabajo previo no registrado"
|
||||
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task adjust TSK-... --minutes -10 --note "Corregir doble conteo"
|
||||
```
|
||||
|
||||
El total efectivo nunca puede quedar negativo.
|
||||
|
||||
### Cambiar estado
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task status TSK-... --status blocked --note "Esperando refacción"
|
||||
```
|
||||
|
||||
Estados admitidos aquí: `backlog`, `todo`, `in_progress`, `blocked`, `cancelled`. Para finalizar use `task done`.
|
||||
|
||||
### Completar
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
task done TSK-... --note "Criterios de aceptación verificados"
|
||||
```
|
||||
|
||||
Si el administrador actual mantiene el temporizador, la CLI lo detiene. Rechaza completar si otra persona sigue registrando tiempo en la misma tarea.
|
||||
|
||||
### Listar
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json task list
|
||||
clusterlog --root . --json task list --status blocked
|
||||
clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub task list --mine
|
||||
clusterlog --root . --json task list --project PRJ-...
|
||||
```
|
||||
|
||||
## 9. Proyectos
|
||||
|
||||
### Crear
|
||||
|
||||
```bash
|
||||
cat examples/project.json | clusterlog \
|
||||
--root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
project create --from-json -
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
- `--title`, `--description`, `--objective`
|
||||
- `--owners`
|
||||
- `--target-date YYYY-MM-DD`
|
||||
- `--status planned|active|blocked|done|cancelled|archived`
|
||||
- `--tags`, `--systems`
|
||||
- `--scope`, `--out-of-scope`
|
||||
- `--milestones`, `--success`
|
||||
- `--body-file ARCHIVO|-`
|
||||
- `--from-json ARCHIVO|-`
|
||||
|
||||
### Listar
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json project list
|
||||
clusterlog --root . --json project list --status active
|
||||
```
|
||||
|
||||
## 10. Documentación y manuales
|
||||
|
||||
```bash
|
||||
cat examples/manual.json | clusterlog \
|
||||
--root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
|
||||
content create --from-json -
|
||||
```
|
||||
|
||||
También acepta:
|
||||
|
||||
```bash
|
||||
clusterlog --root . --commit --ssh-key ~/.ssh/id_ed25519.pub content create \
|
||||
--section manuales \
|
||||
--title "Reemplazar nodo de cómputo" \
|
||||
--description "Procedimiento seguro y validaciones" \
|
||||
--tags runbook,hardware \
|
||||
--systems compute \
|
||||
--body-file reemplazo.md \
|
||||
--weight 20
|
||||
```
|
||||
|
||||
`section` sólo puede ser `documentacion` o `manuales`.
|
||||
|
||||
## 11. Proyección
|
||||
|
||||
```bash
|
||||
clusterlog --root . sync
|
||||
clusterlog --root . sync --check
|
||||
```
|
||||
|
||||
`sync` lee Markdown, administradores y eventos; genera `data/generated/site_state.json`. `--check` no escribe y falla cuando el archivo derivado no coincide con la fuente.
|
||||
|
||||
Los agentes no deben editar `data/generated/site_state.json` a mano.
|
||||
|
||||
## 12. Validación
|
||||
|
||||
```bash
|
||||
clusterlog --root . --json validate
|
||||
clusterlog --root . --json validate --skip-zola
|
||||
clusterlog --root . --json validate --require-zola
|
||||
```
|
||||
|
||||
Se comprueban, entre otros:
|
||||
|
||||
- registro de administradores y `allowed_signers`;
|
||||
- IDs, autores, revisores, owners y assignees;
|
||||
- estados, fechas y referencias de proyectos;
|
||||
- eventos huérfanos o inconsistentes;
|
||||
- temporizadores concurrentes y totales negativos;
|
||||
- secretos probables;
|
||||
- vigencia de la proyección;
|
||||
- plantillas y enlaces con `zola check`, cuando está disponible.
|
||||
|
||||
## 13. Firmas
|
||||
|
||||
```bash
|
||||
clusterlog --root . verify commit HEAD
|
||||
clusterlog --root . verify commit abc1234
|
||||
```
|
||||
|
||||
La verificación usa:
|
||||
|
||||
```text
|
||||
config/allowed_signers
|
||||
namespace: git
|
||||
```
|
||||
|
||||
En CI conviene verificar todos los commits nuevos, no sólo `HEAD`.
|
||||
|
||||
## 14. Esquemas para agentes
|
||||
|
||||
```bash
|
||||
clusterlog --json schema
|
||||
clusterlog --json schema memory
|
||||
clusterlog --json schema task
|
||||
clusterlog --json schema project
|
||||
clusterlog --json schema content
|
||||
```
|
||||
|
||||
Los esquemas siguen JSON Schema 2020-12 y rechazan propiedades adicionales. Esta restricción permite detectar errores ortográficos en nombres de campos.
|
||||
|
||||
## 15. Patrón recomendado para agentes
|
||||
|
||||
```bash
|
||||
set -euo pipefail
|
||||
|
||||
SCHEMA="$(clusterlog --json schema memory)"
|
||||
# Construir input.json con base en data del sobre.
|
||||
|
||||
clusterlog --root . --json --dry-run --ssh-key "$KEY" \
|
||||
memory create --from-json input.json
|
||||
|
||||
RESULT="$(clusterlog --root . --json --commit --ssh-key "$KEY" \
|
||||
memory create --from-json input.json)"
|
||||
|
||||
printf '%s\n' "$RESULT"
|
||||
clusterlog --root . --json verify commit HEAD
|
||||
```
|
||||
|
||||
El agente debe detenerse ante cualquier código distinto de cero y presentar el error al usuario sin ocultarlo.
|
||||
Reference in New Issue
Block a user