bootstrap: iniciar bitácora operativa

2026-08-13 00:43:15 -06:00
commit 1ecfb022b1
85 changed files with 7967 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Instrucciones para agentes de programación
+
+## Propósito
+
+Use `clusterlog` para registrar trabajo operativo de forma atribuible, validada y reproducible. No edite directamente archivos derivados ni simule una identidad.
+
+## Reglas obligatorias
+
+1. Lea `clusterlog --json schema <tipo>` antes de construir una entrada nueva.
+2. No incluya secretos, tokens, contraseñas, llaves privadas ni datos personales innecesarios.
+3. Registre sólo hechos observados. Distinga claramente entre cambio ejecutado, validación ejecutada y recomendación pendiente.
+4. Ejecute primero con `--dry-run` cuando el contenido provenga de una sesión larga o incluya comandos.
+5. Use siempre `--json` y compruebe el código de salida.
+6. Para una escritura final, use `--commit` únicamente cuando el usuario haya autorizado la operación y su mecanismo de firma esté disponible.
+7. Nunca exporte, lea ni copie la llave privada. Pase una ruta autorizada o permita que Git/ssh-agent la maneje.
+8. No edite `data/generated/site_state.json`; ejecute `clusterlog sync`.
+9. No agregue manualmente eventos a un arreglo central. Cada evento debe ocupar su archivo independiente y ser creado por la CLI.
+10. Después de escribir, ejecute `clusterlog validate` y devuelva al usuario ID, ruta, advertencias y SHA del commit.
+
+## Flujo para una memoria de sesión
+
+```bash
+clusterlog --json schema memory > /tmp/memory-schema-envelope.json
+
+cat > /tmp/memory.json <<'JSON'
+{
+  "title": "...",
+  "description": "...",
+  "tags": [],
+  "systems": [],
+  "risk": "low",
+  "review_required": true,
+  "context": "...",
+  "changes": [],
+  "commands": [],
+  "validation": [],
+  "rollback": "...",
+  "agent": "<nombre-del-agente>"
+}
+JSON
+
+clusterlog --root . --json --dry-run --ssh-key "$CLUSTERLOG_SSH_KEY" \
+  memory create --from-json /tmp/memory.json
+
+clusterlog --root . --json --commit --ssh-key "$CLUSTERLOG_SSH_KEY" \
+  memory create --from-json /tmp/memory.json
+
+clusterlog --root . --json validate
+clusterlog --root . --json verify commit HEAD
+```
+
+## Calidad de una memoria
+
+Una memoria útil responde:
+
+- ¿Cuál era el contexto o síntoma?
+- ¿Qué se cambió exactamente?
+- ¿Qué comandos son relevantes, con valores sensibles redactados?
+- ¿Qué resultado se observó?
+- ¿Cómo se validó?
+- ¿Qué riesgo quedó abierto?
+- ¿Cómo se revierte?
+- ¿Qué manual o documento debe actualizarse?
+
+No convierta salidas extensas de terminal en el cuerpo. Resuma y enlace evidencia aprobada.
+
+## Comportamiento ante errores
+
+- `identity_not_found`: deténgase; no elija otra identidad por aproximación.
+- `possible_secret`: redacte y repita el dry-run; no fuerce la escritura.
+- `validation_failed`: presente los códigos y rutas concretas.
+- `git_commit_failed`: no afirme que la operación quedó auditada; los archivos pueden existir sin commit y deben revisarse.
+- `task_has_running_timers`: identifique a los actores; no cierre o borre eventos.
+
+## Cambios al código del proyecto
+
+Antes de entregar:
+
+```bash
+gofmt -w cmd internal
+go test ./...
+go vet ./...
+make build
+./bin/clusterlog --root . sync
+./bin/clusterlog --root . sync --check
+./bin/clusterlog --root . validate --skip-zola
+```
+
+Cuando Zola esté disponible:
+
+```bash
+./scripts/bootstrap-theme.sh
+./bin/clusterlog --root . validate --require-zola
+zola build
+```
+
+Mantenga compatibilidad del JSON. Cualquier cambio de contrato debe actualizar `schema.go`, `CLI.md`, ejemplos y pruebas.