ADR: Knowledge Base vs Graph — Sistema de verificación de drift documental

Contexto

La Biblioteca Supercontexto de CreaRack Pro mantiene ~449 páginas wiki cuyas sources referencian archivos de código real. Con el tiempo, el código evoluciona pero las páginas no se actualizan: se produce drift entre la wiki y el estado real del sistema.

Este ADR documenta la decisión arquitectónica de implementar un sistema de verificación automática de drift en dos capas:

• Capa 1 (reactiva): tripwires disparados en cada commit que tocan código referenciado.
• Capa 2 (proactiva): cron periódico que verifica páginas stale con LLM (Haiku 4.5).

Decisión

Híbrido Knowledge-Base + Graph: mantener el grafo D1 existente como fuente de verdad, extender el schema con campos de lifecycle (kind, lifecycle, verification_pending) y añadir dos handlers MCP nuevos para marcar y evaluar drift, en lugar de migrar a un sistema puramente vectorial o puramente grafal.

Alternativas descartadas

Fases de implementación

Schema D1 extendido (migration 0024, PR workspace #36)

ALTER TABLE bib_wiki_pages ADD COLUMN kind TEXT DEFAULT 'article';
ALTER TABLE bib_wiki_pages ADD COLUMN lifecycle TEXT DEFAULT 'active';
ALTER TABLE bib_wiki_pages ADD COLUMN verification_pending INTEGER DEFAULT 0;

• kind: tipo de página (article, entity_page, decision_page, feature_page, …).
• lifecycle: estado del ciclo de vida (draft, active, archived, stale).
• verification_pending: flag 0/1. Se pone a 1 cuando un tripwire detecta que el código fuente referenciado ha cambiado. El cron lo lee para priorizar verificaciones.

Handlers MCP añadidos en Fase 2 (workspace wiki.ts, PR #37)

bib_mark_verification_pending

Recibe file_paths: string[] + actor: string. Busca en bib_wiki_pages las páginas cuyas sources (type=code) hacen match con alguno de los paths y actualiza verification_pending=1.

• Idempotente. No falla si no encuentra matches.
• Llamado desde trigger_tripwires en bib_ingest.py de ambos repos.

bib_check_drift_for_doc

Recibe slug: string. Usa Haiku 4.5 para comparar el contenido actual de la página wiki con el código fuente referenciado y devuelve una puntuación de drift + recomendación (ok | update | archive).

• Coste estimado cron sobre páginas verification_pending=1: ~$2.4/mes.

Consecuencias

Positivas:

• Detección reactiva inmediata de potencial drift en <60s tras merge.
• Coste LLM diferido: solo se invoca Haiku cuando hay verification_pending=1.
• Non-blocking: errores de tripwire no rompen el pipeline de ingest.

Negativas / trade-offs:

• Requiere mantener coherencia entre sources[].ref en front-matter y paths reales del repo.
• Fase 3 (cron) todavía no activa — el flag verification_pending se acumula sin procesarse hasta Fase 3.
• Paths internos excluidos de tripwires: .github/scripts/bib_*, scripts/harness/, context/.

Véase también

• [[entity—biblioteca—service—drift-checks]]
• [[feature—biblioteca—pulse-drift-checks-widget]]