dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: añadir ADR, diario, CHANGELOG y comando /entrada_diario

Browse Source 
Infraestructura de documentación operativa y de decisiones:

- docs/adr/ — Architecture Decision Records. Incluye plantilla y
  ADR 0001 documentando el experimento y retirada de GitButler.
- docs/diary/ — diario de avances con un archivo por día.
  Primera entrada 2026-04-24.md retrocubriendo esta sesión
  (conectar aurgi-pc, dashboard fn_monitoring, funciones systemd
  locales, ADR GitButler, regla KISS).
- CHANGELOG.md — formato Keep a Changelog para cambios cara a
  usuario/agentes. Sección 2026-04-24 con Added/Changed/Fixed/Removed.
- .claude/commands/entrada_diario.md — slash command para añadir
  entradas al diario con formato consistente.

Separación:
  diary   = contexto operativo diario
  CHANGELOG = qué cambió en el código
  ADR     = por qué se decidió algo
  rules   = reglas operativas del agente

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
egutierrez
2026-04-24 14:27:38 +02:00
parent a92213853d
commit 7597549fcf
6 changed files with 323 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/0001-gitbutler-experiment.md
+61
View File
@@ -0,0 +1,61 @@
# ADR 0001 — Experimento con GitButler para trabajo paralelo
- **Fecha:** 2026-04-24
- **Estado:** rejected
## Contexto
El flujo de trabajo en `fn_registry` a menudo toca varias tareas simultáneamente: issues independientes en distintos dominios, features nuevas, fixes rápidos, docs. Con `git` + ramas tradicionales esto obliga a `git stash` / `checkout` constantes o a mezclar cambios en una misma rama.
Se planteó **GitButler** (virtual branches) como herramienta para mantener múltiples líneas de trabajo activas en el mismo working tree sin dance de stash/checkout, con push independiente de cada VB a su rama remota en Gitea.
Restricciones relevantes del entorno:
- Repo grande con **submódulos C++** activos (`cpp/vendor/imgui`, `implot`, `tracy`, `glfw`) usados por apps nativas.
- Archivos "puente" que casi siempre se tocan: `go.mod`, `python/uv.lock`, `registry.db`, `frontend/pnpm-lock.yaml`.
- Flujo de commit/push integrado con agentes de Claude Code.
## Decisión
Se **instaló y probó** GitButler durante una sesión de trabajo:
- Binario `~/.local/bin/but` (37 MB).
- Plugin `gitbutler-tools` en el marketplace de Claude Code.
- Skill `gitbutler` en `repo_Claude/.claude/skills/gitbutler/`.
- Hooks `PreToolUse`, `PostToolUse`, `Stop` en `settings.json` invocando `but claude ...`.
- Sección dedicada en el SKILL.md del agente `gitea` explicando cómo combinar VBs con issues y PRs.
Se inició trabajo usando virtual branches: rama de workspace `gitbutler/workspace`, virtual branches `e-branch-1/2/3`, VB creada manualmente `fn-monitoring-setup`.
## Alternativas consideradas
1. **Mantener `git` + ramas tradicionales** (status quo). Conocido, sin deps extra, compatible con todo lo ya existente.
2. **`git worktree` + varias checkouts** para paralelizar sin stash.
3. **GitButler virtual branches** — opción experimentada.
## Consecuencias del experimento (problemas encontrados)
1. **Bugs con submódulos**: al añadir/modificar `.gitmodules` junto con gitlinks (`cpp/vendor/glfw`) GitButler no podía commitear el cambio; creaba commits vacíos (0 files changed) o metía contenido de otros cambios "unassigned" en el commit. Fue necesario recurrir a `git commit --no-verify` para saltarse el pre-commit hook, lo que a su vez rompía el modo GitButler y obligaba a `but teardown`.
2. **Auto-commits con el texto del chat como mensaje**: el plugin de Claude Code hacía snapshots automáticos tras cada edición con el **texto literal del turno del usuario** como commit message. Ejemplo real: `56c7c3f3 haz que cree servicio de sistema , instalado el mingw`.
3. **Pre-commit hook que bloquea `git commit` directo**: obliga a usar `but commit` o a añadir `--no-verify`, que a su vez rompe el modo GitButler.
4. **Overhead de herramientas**: binario 37 MB + plugin + skill + hooks + entrada en marketplace. Mucha superficie para gestionar.
5. **Falla silenciosa de `but commit`**: mensajes `Warning: Some selected changes could not be committed` sin detalle de qué no se incluyó.
6. **Complicación con `rm`/`--no-verify`**: al salir de GitButler (`but teardown`) quedan ramas fantasma (`gitbutler/workspace`, `gitbutler/target`, `e-branch-*`) y estado interno (`.git/gitbutler/`).
## Decisión final
**Retirar GitButler completamente**:
- `but teardown` para salir del modo workspace.
- Eliminación del binario, plugin, skill, hooks, config, ramas y estado interno. Documentado en commit `a5ab498` de `repo_Claude`.
- Consolidación de los commits útiles de la sesión (registry.db untrack, submódulo GLFW, 7 funciones systemd locales, pipeline `install_systemd_service`) en 2 commits limpios sobre `master` de `fn_registry`.
## Aprendizaje
Se deriva una **regla KISS** formal ([`.claude/rules/kiss.md`](../../.claude/rules/kiss.md)):
- Antes de adoptar una herramienta externa, medir la fricción real del flujo actual. Si no duele, añadir capas no ayuda.
- Cuestionar cada nueva dependencia: coste de instalación + mantenimiento + aprendizaje + riesgo upstream vs. beneficio concreto y medible.
- Preferir lo que ya tenemos (`git`, submódulos, `fn` CLI) antes que soluciones "generalistas" con más superficie.
Para el caso concreto de trabajo paralelo, si vuelve a surgir la necesidad, la siguiente alternativa a explorar sería `git worktree` — ya soportado por `git` nativo, sin deps extra, sin hooks externos.
docs/adr/README.md
+61
View File
@@ -0,0 +1,61 @@
# Architecture Decision Records (ADR)
Esta carpeta guarda las **decisiones de diseño importantes** que afectan a `fn_registry` y sus apps — qué se decidió, por qué, y qué aprendimos.
No son reglas operativas (esas viven en `.claude/rules/`). Son **historia de decisiones**: útil para saber cómo llegamos al estado actual, qué experimentos descartamos y por qué no volver a tomar el mismo camino.
## Formato
Un archivo por decisión. Convención de nombre:
```
NNNN-slug-corto.md
```
Donde:
- `NNNN` es un número incremental (0001, 0002, ...)
- `slug-corto` en kebab-case, descriptivo pero breve
## Plantilla
```markdown
# ADR NNNN — Título corto
- **Fecha:** YYYY-MM-DD
- **Estado:** proposed | accepted | rejected | superseded | deprecated
- **Supersede a:** (opcional, link a otro ADR)
## Contexto
Qué problema/pregunta/situación motiva esta decisión. Qué restricciones hay.
## Decisión
Qué se decidió hacer. Concreto y accionable.
## Alternativas consideradas
Lista breve de otras opciones y por qué se descartaron.
## Consecuencias
Cambios concretos derivados: archivos, reglas, herramientas, flujos.
## Aprendizaje (si aplica, cuando se revisita)
Qué se aprendió después. Útil cuando un ADR se supersede.
```
## Estados
- **proposed** — en discusión, aún sin decidir
- **accepted** — decisión vigente
- **rejected** — se propuso y se descartó (se deja el ADR para entender por qué)
- **superseded** — sustituido por un ADR posterior (indicar cuál)
- **deprecated** — la decisión ya no aplica (contexto cambió)
## Índice
| # | Título | Estado |
|---|--------|--------|
| [0001](0001-gitbutler-experiment.md) | Experimento con GitButler para trabajo paralelo | rejected |
docs/diary/2026-04-24.md
+55
View File
@@ -0,0 +1,55 @@
# 2026-04-24
## 12:00 — Conectar aurgi-pc al registry server
Primera sesión en aurgi-pc (WSL). Vincular este PC al server centralizado y recuperar metadata de apps/projects/analysis/vaults existentes.
- Hecho: recompilado `fn` con `CGO_ENABLED=1 -tags fts5` desde `/usr/local/go/bin/go` (go1.25.0). Ahora tiene `fn sync`.
- Hecho: `~/.fn_pc` = `aurgi-pc`. Env vars `FN_REGISTRY_API` y `REGISTRY_API_TOKEN` desde `pass`.
- Hecho: `fn sync` contra `https://registry.organic-machine.com` — 44 enviados, 62 recibidos, aurgi-pc registrado con 18 locations.
- Hecho: `registry.db` gitignorada (regenerable con `fn index` + `fn sync`).
- Aprendizaje: GPG sin TTY en WSL obliga a desbloquear `pass` en terminal real una vez; caché de gpg-agent (ver [memoria feedback_gpg_pass_wsl](../../.claude/projects/memory)).
## 13:00 — Instalar dashboard fn_monitoring
Configurar el proyecto `fn_monitoring` (API + dashboard ImGui) en aurgi-pc para visualizar las apps.
- Hecho: clonado `registry_dashboard` + movido a `projects/fn_monitoring/apps/registry_dashboard/`.
- Hecho: inicializados submódulos `cpp/vendor/{imgui,implot}`. Re-registrado `glfw` como submódulo (antes tenía path `/home/lucas/...` heredado que bloqueaba `git submodule status`).
- Hecho: build Linux del dashboard (12.9 MB).
- Hecho: `projects/fn_monitoring/launcher.sh` — arranca API si no está viva + lanza dashboard + cleanup al salir.
- Fixed: `http_client.cpp` requería `#include <cstdint>` explícito (mingw más estricto que g++ Linux). Commit en subrepo del dashboard.
- Hecho: cross-compile Windows (19 MB) + copiado a `/mnt/c/Users/egutierrez/Desktop/registry_dashboard.exe`.
## 13:30 — Funciones systemd locales + servicio sqlite_api
Hasta ahora solo había funciones systemd remotas (via SSH para VPS). Crear versiones locales y registrar `sqlite_api` como servicio del sistema.
- Hecho: 6 funciones bash/infra — `systemd_local_{install_unit, enable, start, restart, status, uninstall}`.
- Hecho: pipeline bash/pipelines — `install_systemd_service` que compone las anteriores; genera unit file con env vars deterministas.
- Hecho: compilado `sqlite_api` como binario (antes `go run`) en `projects/fn_monitoring/apps/sqlite_api/sqlite_api`.
- Hecho: servicio `sqlite_api.service` instalado + enabled + active. Queda vivo al arrancar WSL (systemd=true en `/etc/wsl.conf`).
- Fixed: bugs en `systemd_local_{enable,start,restart}` que contaminaban stdout con mensajes de `systemctl` rompiendo el `$(...)` del pipeline. Redirigido a stderr.
## 14:00 — Experimento GitButler y retirada
Se probó GitButler para trabajo paralelo con virtual branches. Descartado.
- Problema: bugs graves con submódulos + gitlinks — `but` creaba commits vacíos o con contenido cruzado cuando se tocaba `.gitmodules`.
- Problema: auto-commits usaban el texto del turno del chat como commit message.
- Hecho: `but teardown` + eliminación completa (binario, plugin, skill, hooks en settings.json, config git, ramas fantasma).
- Hecho: commits consolidados en `master` de `fn_registry` (3 limpios) + push a origin.
- Hecho: documentado en [ADR 0001](../adr/0001-gitbutler-experiment.md).
## 14:30 — Formalizar filosofía KISS + docs
Derivar una regla operativa del aprendizaje de GitButler y preparar la infraestructura de documentación.
- Hecho: [`.claude/rules/kiss.md`](../../.claude/rules/kiss.md) + entrada #16 en `.claude/rules/INDEX.md`.
- Hecho: `docs/adr/` con README y ADR 0001.
- Hecho: `docs/diary/` con README y esta primera entrada.
- Hecho: `CHANGELOG.md` raíz retrocubriendo toda la sesión.
- Hecho: `/entrada_diario` slash command para añadir entradas rápido.
Pendiente:
- Lanzar el dashboard y verificar que muestra las 12 apps en la UI (tarea #9) — requiere terminal real con DISPLAY WSLg.
docs/diary/README.md
+38
View File
@@ -0,0 +1,38 @@
# Diario — fn_registry
Registro diario de avances: qué se trabajó, qué se completó, qué queda pendiente.
Un archivo por día con nombre `YYYY-MM-DD.md`. Dentro, una sección por bloque de trabajo con timestamp.
## Cuándo usar cada tipo de registro
| Archivo | Para qué | Granularidad |
|---------|----------|--------------|
| `docs/diary/YYYY-MM-DD.md` | **Qué hicimos hoy**. Contexto operativo, decisiones rápidas, cosas pendientes para mañana. | Diario |
| `CHANGELOG.md` (raíz) | **Qué cambió en el código** cara al usuario/agentes. Add/Change/Fix/Remove. | Por release o por hito |
| `docs/adr/NNNN-*.md` | **Por qué** tomamos una decisión arquitectural. | Ocasional |
Reglas:
- Nunca reescribir entradas antiguas — si algo cambia, añadir una nota nueva.
- Preferir bullet points breves a párrafos largos.
- Enlazar a commits, issues, ADRs o funciones del registry cuando aplique.
## Añadir una entrada
Usar el comando `/entrada_diario <descripción>`. Crea el archivo del día si no existe y añade una sección con hora actual.
## Formato de una entrada
```markdown
# YYYY-MM-DD
## HH:MM — Título corto
Contexto en 1-3 líneas.
- Hecho: viñeta
- Hecho: viñeta
- Pendiente: viñeta
Referencias: commit SHA, ADR #NNNN, issue #N
```