Sistema Supercontexto · wiki auto-mantenida con grafo D1

ADR — Sistema Supercontexto · wiki auto-mantenida con grafo D1

Contexto

CreaRack Pro es una plataforma SaaS desarrollada por un equipo de dos developers (Edu y Dani) con apoyo de un agente Claude Code por persona. El codebase ronda los ~509 endpoints Django Ninja repartidos en una docena de apps, ~3800 nodos indexados en grafo (Python + TypeScript), y una superficie funcional amplia (Rack Editor, Map Editor, Network Observatory, Signage CMS, Local Agent, Terminal SSH, CNS).

A finales de 2025 la documentación vivía dispersa en una decena de docs raíz (CLAUDE.md, README.md, ARCHITECTURE.md, BACKEND.md, FRONTEND.md, DEVOPS.md, etc.) más comentarios de código y conversaciones efímeras con Claude. Cada vez que un agente abría una sesión nueva, el contexto se reconstruía desde cero: leer 30k+ líneas de markdown, deducir relaciones entre módulos, redescubrir decisiones que ya se habían tomado meses atrás. La señal a ruido caía conforme crecía el corpus, y los devs duplicaban trabajo sin saberlo.

Tres incidentes recurrentes empujaron a formalizar un sistema:

• Decisiones reinventadas — CONN_MAX_AGE se revertió incorrectamente cuatro veces en producción porque la razón vivía en commits viejos sin documento canónico.
• Drift docs ↔ código — guías describiendo arquitectura ya refactorizada, sin nadie marcando staleness.
• Coste cognitivo de onboarding del agente — abrir Claude Code en un repo grande y conseguir contexto útil exigía 30+ minutos de exploración cada sesión.

Problema

¿Cómo se mantiene una memoria persistente, consultable y auto-curada del proyecto, accesible tanto por humanos como por agentes Claude, sin que su mantenimiento sea otro trabajo a tiempo parcial para un equipo de dos personas?

Restricciones:

• Equipo pequeño: ningún humano puede dedicar horas semanales a mantener docs.
• Multi-repo: CreaRack-Pro (Django) + workspace (Astro/CF Pages) + claude-method comparten conocimiento.
• Multi-agente: dos instancias de Claude Code (Edu y Dani) con memoria independiente, más subagentes y crons LLM.
• Presupuesto acotado: budget API mensual del orden de decenas de dólares, no cientos.
• Sin SPOF en máquinas de devs (Regla 17): la infraestructura del conocimiento debe vivir en servicios compartidos, no en Task Schedulers locales.

Opciones consideradas

1. Status quo · docs dispersos en MD raíz crece infinito. Cero infraestructura nueva, cero coste, cero curaduría. Cero recuperación al crecer. La memoria se desborda cada 6 meses y nadie sabe qué borrar. Descartada — es lo que ya tenían y produjo los incidentes que motivan este ADR.

2. Notion / Outline / Confluence externo. Solución madura, búsqueda decente, multi-usuario. Pero rompe la regla “docs vive con el código” (no commitea, no diff, no PR), introduce un proveedor SaaS adicional con coste por usuario, no es accesible por agentes Claude sin integración custom, y la curaduría sigue siendo manual. Descartada — coste de fricción humano + dependencia externa + opacidad para agentes.

3. Obsidian local sin grafo D1 ni ingest automático. Vault markdown en repo, abre en Obsidian, da grafo visual gratis. Funciona para humanos pero no para agentes (Claude Code no consulta Obsidian) y la curaduría sigue siendo 100% manual: detectar staleness, completar related:, archivar drafts, todo a mano. Parcialmente útil — adoptada como capa visual complementaria, no como sistema completo.

4. Wiki estática Astro sin grafo ni ingest LLM. Sólo Markdown renderizado en workspace.crearack.com/wiki. Mejora consulta humana pero no resuelve drift ni cobertura. Edu/Dani siguen escribiendo docs a mano y nadie verifica que sigan siendo verdad. Descartada — resuelve presentación, no mantenimiento.

5. Sistema Supercontexto · Astro + D1 + MCP + crons GHA + ingest LLM. Wiki como contenido Astro versionado en repo, espejada en tabla bib_wiki_pages de Cloudflare D1, indexada en grafo (bib_* tables) y en Archivo Maestro vectorial (Workers AI bge-m3). Mutaciones via 12 tools MCP wiki_*. Ingest automático post-merge a main usando un pipeline LLM 3-tier (filtro pre-LLM gratis → triage Haiku → loop Sonnet con prompt caching) que crea/actualiza pages a partir de los diffs. Crons GHA de mantenimiento (Curator, Lint stale/orphans, Lint contradictions, utility_score, weekly report, catalog regen). Skills CLI bib-* y wiki-* para acciones manuales puntuales. Sensor “Bibliotecario” en dashboard del workspace + sección “Bibliotecario · 7d” en Pulse para visibilidad operativa. Seleccionada.

Decisión

Se adopta Supercontexto como sistema único de gestión del conocimiento del proyecto. El sistema se compone de cinco subsistemas que se entregaron como Fases 0-6 más Fase 7 (TypeScript Graphify):

1. Backbone D1 + MCP (Fase 1) — 4 tablas bib_wiki_* + 12 tools MCP + schema Zod compartido + pre-commit check de front-matter.
2. Backfill al schema (Fase 2) — 220 pages migradas con 4 subagentes Opus paralelos en sesión 17 (corpus al 100% Supercontexto, 0 legacy).
3. Ingest automático (Fases 3 + 3.5) — workflow GHA post-merge con trigger híbrido pull_request: closed + push: main, pipeline 3-tier que abarata el coste 80% ($50/mes a ~$10/mes).
4. Query con cierre + Lint + Métricas (Fases 4-6) — bib_ask archiva respuestas valiosas como drafts (Curator decide promote/delete), wiki_lint_bulk y wiki_lint_contradictions corren en cron, wiki_utility_recompute puntúa pages por uso real (query_hit en bib_ask).
5. TypeScript Graphify (Fase 7) — extractor bib_ast_ts.mjs añade 669 nodos TS al grafo (3170 → 3839), cierra el gap “código TypeScript invisible para bib_search_nodes”.

Arquitectura operativa:

• Todo el contenido vive en src/content/wiki/*.md (Astro Content Collections) y se espeja a bib_wiki_pages en D1 vía el ingest. La sincronización D1 ↔ repo es bidireccional (branch reconcile_wiki_to_d1 en bib_ingest.py desde sesión 18, ver [[feature--supercontext--reconcile-d1-repo]]).
• 6 tipos de pages canónicos: concept_page (qué es), feature_page (qué cambia), entity_page (qué objeto), runbook_page (cómo hacerlo), decision_page (por qué se eligió), incident_page (qué falló).
• 7 crons activos en GitHub Actions más el deploy trigger de CF Pages. Toggle BIBLIOTECARIO_PAUSADO=true permite pausar consumo Anthropic durante planes intensivos sin desplegar nada.
• Skills CLI replicadas en CreaRack-Pro y workspace (5 skills wiki-* + bib-*).
• Visibilidad: sensor “Bibliotecario” en / del workspace, sección “Bibliotecario · 7d” en /biblioteca/pulse, informe semanal automático en public/supercontext/reports/.

Reglas de Oro asociadas: Regla 0 (Biblioteca primero), Regla 19 (arranque/cierre Supercontexto), Regla 20 (push vs PR híbrido), Regla 17 (no SPOF), Regla 15 (HTTP 200 ≠ éxito).

Consecuencias

Positivas

• Onboarding instantáneo del agente — bib_ask da respuesta sintetizada con fuentes en segundos. Sesiones empiezan productivas, no exploratorias.
• Memoria persistente compartida — Edu y Dani ven el mismo corpus, los dos Claude Codes consultan la misma base. Decisiones no se reinventan.
• Auto-curaduría real — Curator triages drafts, Lint detecta stale/orphans/contradictions, weekly report archiva la salud del sistema. La intervención humana es revisión de veredictos, no producción de docs.
• Ahorro de coste vs equivalentes manuales — pipeline 3-tier gasta ~$10/mes; un editor técnico humano costaría órdenes de magnitud más.
• Descubribilidad humana — Obsidian sobre src/content/wiki/ da grafo navegable; INDEX.md curado + catalog.md auto-generado dan dos vistas complementarias.

Negativas / trade-offs honestos

• Coste recurrente API Anthropic — ~$10/mes de baseline (ingest + Curator + Lint contradictions). Plan Max no cubre llamadas API directas, sólo Claude Code interactivo + subagentes Agent (decisión registrada sesión 26). El gasto es real y sale de tarjeta de crédito todos los meses.
• Dependencia de proveedores externos — Anthropic (Claude Sonnet/Haiku para ingest y triage), Google (Gemini 2.5 Flash para síntesis), Cloudflare (D1 + Workers AI + Pages). Una caída prolongada de cualquiera degrada el sistema. Mitigación parcial: el corpus markdown sigue siendo legible sin ningún servicio (es git puro).
• Latencia de ingest — el reflejo en wiki tras un commit puede tardar 1-3 minutos. Aceptable para conocimiento, no para feedback en línea.
• Complejidad operativa de 7+ crons — cada workflow GHA puede fallar silenciosamente (Regla 15). Hizo falta sensor + zombie reaper (sesión 25) para detectar runs colgados. La operación tiene su propia carga aunque sea menor que mantener docs a mano.
• Footgun resuelto pero recordado: drift D1 ↔ repo — durante meses los commits docs-only saltaban el ingest LLM y no propagaban a D1, dejando el grafo desincronizado del corpus. Resuelto en sesión 18 con el branch reconcile + upsert vía wiki_index_metadata. La lección: cualquier ruta de mutación que NO pase por el handler oficial (ej. git commit directo) necesita un reconciler.
• Riesgo de over-engineering para 2 devs — un equipo de esta talla podría haber sobrevivido sin sistema. La justificación es que los agentes Claude lo amortizan: el tiempo ahorrado en re-explicarles contexto cada sesión paga el coste de mantenerlo. Si Edu/Dani dejan de usar Claude Code en serio, Supercontexto se vuelve injustificable y debería desmontarse.
• Curaduría humana sigue siendo necesaria — Curator opera en dry_run=true por defecto durante observación inicial; la promoción definitiva de drafts a active requiere revisión humana o varios días de veredictos consistentes. El “cero esfuerzo humano” es un asíntota, no un estado actual.

Status

Accepted. Plan cerrado en sesión 22 (tag supercontext/plan-complete, 2026-04-24). En modo operativo desde entonces — backlog observacional + crons reactivos + 5 iniciativas post-audit (I1-I5) en ejecución desde sesión 26. Cualquier cambio de alcance que altere los pilares (D1 como espejo, MCP como única ruta de mutación oficial, ingest 3-tier, 6 tipos canónicos) requiere nuevo ADR y aprobación explícita de Edu.

Véase también

• [[concept—biblioteca—supercontexto]] — concepto raíz del sistema, las 3 capas Grafo + Archivo Maestro + Wiki.
• [[feature—supercontext—reconcile-d1-repo]] — branch reconcile que cierra el drift D1 ↔ repo.
• [[feature—supercontexto—weekly-report]] — informe semanal automático del estado del sistema.
• [[runbook—biblioteca—manual-reindex]] — runbook para reindexar el grafo manualmente.
• [[runbook—wiki—obsidian-setup]] — runbook para abrir el corpus como vault Obsidian.
• [[decision—20260403—multi-tenancy-rls]] — ADR hermano · aislamiento multi-tenant.
• [[decision—20260401—module-gating]] — ADR hermano · gating por módulos SaaS.
• [[decision—20260422—ingest-3-tier]] — ADR hermano · pipeline LLM 3-tier que abarata Supercontexto.
• [[decision—20260422—lint-two-tier]] — ADR hermano · estrategia Lint en dos capas.