From 32fc008cae3f6b5254d4542fbaabbbc4541fc15f Mon Sep 17 00:00:00 2001 From: egutierrez Date: Fri, 24 Apr 2026 14:27:38 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20a=C3=B1adir=20ADR,=20diario,=20CHANGELO?= =?UTF-8?q?G=20y=20comando=20/entrada=5Fdiario?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .claude/commands/entrada_diario.md | 69 +++++++++++++++++++++++++++ CHANGELOG.md | 39 +++++++++++++++ docs/adr/0001-gitbutler-experiment.md | 61 +++++++++++++++++++++++ docs/adr/README.md | 61 +++++++++++++++++++++++ docs/diary/2026-04-24.md | 55 +++++++++++++++++++++ docs/diary/README.md | 38 +++++++++++++++ 6 files changed, 323 insertions(+) create mode 100644 .claude/commands/entrada_diario.md create mode 100644 CHANGELOG.md create mode 100644 docs/adr/0001-gitbutler-experiment.md create mode 100644 docs/adr/README.md create mode 100644 docs/diary/2026-04-24.md create mode 100644 docs/diary/README.md diff --git a/.claude/commands/entrada_diario.md b/.claude/commands/entrada_diario.md new file mode 100644 index 00000000..e4d7b0db --- /dev/null +++ b/.claude/commands/entrada_diario.md @@ -0,0 +1,69 @@ +# /entrada_diario — Añadir entrada al diario del día + +Añade una entrada nueva a `docs/diary/YYYY-MM-DD.md` con la fecha y hora actuales. Si el archivo del día no existe, lo crea con el encabezado del día. Si existe, **añade** una sección nueva al final (nunca sobrescribe ni reescribe entradas previas). + +## Uso + +``` +/entrada_diario +``` + +Si no se pasa argumento, resume la sesión actual de forma concisa (qué hicimos, qué completamos, qué queda pendiente). + +## Pasos que debe seguir el asistente + +1. **Fecha y hora**: + ```bash + DATE=$(date +%Y-%m-%d) + TIME=$(date +%H:%M) + ``` + +2. **Ruta del archivo del día**: `docs/diary/${DATE}.md` + +3. **Si el archivo NO existe**, crearlo con: + ```markdown + # ${DATE} + ``` + +4. **Componer la entrada** en este formato exacto: + ```markdown + + ## ${TIME} — + + <1-3 líneas de contexto breve si aplica> + + - Hecho: + - Hecho: + - Pendiente: + + + ``` + +5. **Añadir al final del archivo** (nunca editar secciones anteriores). Usar `Write` con el contenido completo si es el primer uso del día, `Edit` para append en días ya empezados. + +## Reglas de estilo + +- **Viñetas breves**, no párrafos. Si un punto necesita explicación larga, probablemente es un ADR en lugar de un diario. +- **Verbos en pasado para lo hecho**, infinitivo para lo pendiente. +- **Enlaces a artefactos**: commits (`SHA` corto de 7-8 chars), ADRs (`[0001](../adr/0001-...)`), funciones del registry por ID. +- **No duplicar con CHANGELOG**: el diario es contexto operativo ("qué hice hoy"), el CHANGELOG es "qué cambió cara al usuario". +- Si el argumento es vacío, revisar TaskList + cambios en git (`git log --since=today`, `git status`) y resumir en 3-5 viñetas. + +## Ejemplos + +``` +/entrada_diario cerrado issue #23 del dashboard, fix en http_client.cpp +``` + +``` +/entrada_diario # sin args → resume sesión +``` + +## Relación con otras formas de registro + +| Si quieres documentar... | Usa | +|--------------------------|-----| +| Qué trabajé hoy | `/entrada_diario` → `docs/diary/` | +| Qué cambió en el código (cara usuario/agentes) | Editar `CHANGELOG.md` directamente | +| Por qué tomamos una decisión arquitectural | Nuevo ADR en `docs/adr/NNNN-*.md` | +| Una regla operativa nueva del registry | Nuevo archivo en `.claude/rules/` + entrada en INDEX.md | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..239d8ad8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,39 @@ +# Changelog + +Todos los cambios notables de `fn_registry` se documentan aquí. + +Formato basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/). Al no haber releases semver formales, las entradas se ordenan por fecha. + +Para contexto detallado del trabajo diario ver `docs/diary/`. Para decisiones arquitecturales ver `docs/adr/`. + +## [Unreleased] + +## 2026-04-24 + +### Added + +- 6 funciones `bash/infra/systemd_local_*` (install_unit, enable, start, restart, status, uninstall) para gestionar servicios systemd del sistema desde el registry (complementa las versiones remotas SSH ya existentes). +- Pipeline `install_systemd_service_bash_pipelines` que compone las anteriores: genera unit file + install + enable + start + status. +- Servicio systemd `sqlite_api.service` instalado y habilitado en aurgi-pc — arranque automático al iniciar WSL en `127.0.0.1:8484`. +- `projects/fn_monitoring/launcher.sh` — launcher del dashboard (arranca API si no está + lanza ventana + cleanup). +- Regla [`.claude/rules/kiss.md`](.claude/rules/kiss.md) — filosofía KISS para proyectos y apps. +- Documentación ADR en `docs/adr/` con plantilla y ADR 0001 (experimento GitButler). +- Diario en `docs/diary/` + slash command `/entrada_diario` para añadir entradas. +- `CHANGELOG.md` (este archivo). +- Submódulo `cpp/vendor/glfw` re-registrado con path limpio (antes heredado con path absoluto `/home/lucas/...`). +- aurgi-pc registrado en el server centralizado (`registry.organic-machine.com`) con 18 pc_locations. + +### Changed + +- `registry.db` ahora está gitignorada. Es regenerable con `fn index` + completable con `fn sync`. Evita conflictos entre ramas y PCs. +- `sqlite_api` ahora se distribuye como binario compilado (`projects/fn_monitoring/apps/sqlite_api/sqlite_api`) en lugar de `go run` al vuelo. + +### Fixed + +- `http_client.cpp` del dashboard: añadido `#include ` requerido por mingw-w64 para cross-compile Windows (g++ Linux lo incluía transitivamente). +- `systemd_local_{enable,start,restart}`: stdout de `systemctl` redirigido a stderr para no contaminar el JSON capturado por el pipeline. +- `.gitmodules`: entry fantasma `cpp/vendor/glfw` con path absoluto `/home/lucas/...` que bloqueaba `git submodule status` y el cross-compile Windows. + +### Removed + +- Integración de GitButler de Claude Code — binario `~/.local/bin/but`, plugin `gitbutler-tools`, skill `.claude/skills/gitbutler/`, hooks en `settings.json`, ramas `gitbutler/*` + `e-branch-*`, estado interno `.git/gitbutler/`. Ver [ADR 0001](docs/adr/0001-gitbutler-experiment.md) para motivos. diff --git a/docs/adr/0001-gitbutler-experiment.md b/docs/adr/0001-gitbutler-experiment.md new file mode 100644 index 00000000..cf0356e3 --- /dev/null +++ b/docs/adr/0001-gitbutler-experiment.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..e01f06a2 --- /dev/null +++ b/docs/adr/README.md @@ -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 | diff --git a/docs/diary/2026-04-24.md b/docs/diary/2026-04-24.md new file mode 100644 index 00000000..2098c3f3 --- /dev/null +++ b/docs/diary/2026-04-24.md @@ -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 ` 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. diff --git a/docs/diary/README.md b/docs/diary/README.md new file mode 100644 index 00000000..dff2efa8 --- /dev/null +++ b/docs/diary/README.md @@ -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 `. 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 +```