ADR · KB vs Graph — Sistema de detección de drift documental

ADRactivecreado Thu May 14#biblioteca #wiki #supercontext #drift-detection #observability #reliability #cloudflare #d1

Contexto

La Biblioteca (Supercontexto) de CreaRack Pro mantiene páginas wiki cuyas sources[] apuntan a archivos de código reales. Con el tiempo, esos archivos cambian y las páginas quedan stale (desfasadas) sin que nadie lo sepa. Se estimaron ~84 páginas potencialmente obsoletas en el backfill inicial.

El problema tiene dos vertientes:

KB (Knowledge Base) — las páginas wiki con sources: [{type: "code", ref: "..."}] no se actualizan automáticamente cuando cambia el código fuente.
Graph — el grafo de conocimiento en D1 tampoco refleja esos cambios hasta que el próximo ingest los procesa explícitamente.

Era necesario un mecanismo de détection proactiva de drift que marcase páginas para revisión sin bloquear el pipeline de ingest.

Decisión

Implementar un sistema de tripwires de 5 fases que cubre esquema, ingest, handlers MCP, cron de verificación y métricas:

Fase	Descripción	Estado
Fase 0	ADR + TASK.md entry	✅ completada
Fase 1	Schema Astro + D1 migration 0024 + script migración 449 páginas. Campos `kind`, `lifecycle`, `verification_pending` añadidos a `bib_wiki_pages`.	✅ 14-05-2026 (PR workspace #36)
Fase 2	Handlers MCP `bib_mark_verification_pending` + `bib_check_drift_for_doc` (Haiku 4.5). `bib_ingest.py` extendido con `trigger_tripwires` en workspace y CreaRack-Pro. Coste estimado cron: ~$2.4/mes.	✅ 14-05-2026 (PR workspace #37 + PR CreaRack-Pro #34)
Fase 3	Cron `wiki-drift-check.yml` dry-run inicial 2 semanas.	🔲 pendiente
Fase 4	Lint bulk evolucionado + activación final + backfill 84 stale.	🔲 pendiente
Fase 5	Iteración prompt + docs finales + métricas Pulse.	🔲 continua

Alternativas consideradas

Polling periódico puro (sin tripwires): descartado porque no correlaciona cambio de código con página wiki afectada; genera revisiones aleatorias y no priorizadas.
Re-ingest completo en cada push: demasiado costoso (tokens + tiempo); el Tier 1 pre-LLM ya filtra commits, pero no sirve para retroalimentar páginas existentes.
Solo lint en cron semanal: insuficiente, detecta stale pero no actúa; sigue requiriendo intervención manual.

Consecuencias

Positivas

Las páginas wiki con sources de código se marcan automáticamente con verification_pending=1 cuando el archivo fuente cambia, sin intervención humana.
El handler bib_check_drift_for_doc (Haiku 4.5) puede analizar el drift real y proponer actualizaciones a bajo coste.
Pipeline de ingest idempotente: los tripwires disparan antes de los Tiers 1/2/3, independientemente de si el commit se procesa o se salta.
Coste estimado controlado: ~$2.4/mes para el cron de drift detection.

Negativas / trade-offs

Añade complejidad al pipeline bib_ingest.py (función trigger_tripwires con filtro de paths).
Requiere que el MCP bib_mark_verification_pending esté siempre disponible; si falla, se loguea pero no se aborta el ingest (diseño fail-safe).
Las Fases 3-5 aún pendientes: hasta que el cron esté activo, las marcas verification_pending se acumulan sin procesarse.

Schema D1 (Fase 1)

Nuevos campos en tabla bib_wiki_pages:

kind               TEXT    DEFAULT 'wiki'      -- 'wiki' | 'doc' | 'agent_ref' | ...
lifecycle          TEXT    DEFAULT 'active'    -- 'active' | 'draft' | 'archived'
verification_pending INTEGER DEFAULT 0        -- 1 = marcada para revisión de drift

Migration aplicada: 0024_kb_vs_graph_schema.sql en D1 remoto (14-05-2026).

Véase también

[[feature—biblioteca—kb-vs-graph-fase-2-tripwires]]