Rediseño del sistema de mantenimiento documental · Knowledge Base vs Knowledge Graph + lifecycle + tripwires

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

Alternativa	Motivo de descarte
Pure vector store (pgvector/Pinecone)	Pierde navegabilidad del grafo; coste operacional alto
Reescritura total del pipeline	Riesgo alto, no justificado; el grafo D1 ya funciona
Solo cron sin tripwires	Latencia alta (días) entre cambio de código y detección

Fases de implementación

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

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]]