KB vs Graph Fase 2 · Tripwires de verificación en bib_ingest

Qué hace

La Fase 2 del sistema KB vs Graph introduce el mecanismo de tripwires automáticos en el pipeline bib_ingest.py. Cada vez que un commit llega a main, antes de que el ingest decida si procesa o salta el PR (Tiers 1/2/3), se ejecuta trigger_tripwires() para marcar las páginas wiki cuyos sources de código coinciden con los archivos modificados.

Esto cierra la brecha entre “código cambia” y “wiki queda stale sin saberlo”.

Componentes implementados

1. trigger_tripwires() — bib_ingest.py (Pieza 2A)

def trigger_tripwires(changed_files: list[str], mcp_token: str) -> dict:
    """ADR knowledge-base-vs-graph Fase 2 (Pieza 2A).

    Llama al MCP bib_mark_verification_pending con los paths de código tocados
    en este commit. El handler busca en bib_wiki_pages las pages cuyas sources
    tipo 'code' matchean alguno de esos paths y marca verification_pending=1.
    """

Comportamiento:

• Filtra paths internos al proceso de ingest (bib_*, scripts/harness/, context/) para evitar auto-marcado espurio.
• Llama al MCP bib_mark_verification_pending con los paths filtrados.
• Fail-safe: si el MCP devuelve error, se loguea pero el ingest continúa.
• Idempotente: marcar verification_pending=1 dos veces es neutro.
• Tiempo de ejecución estimado: ~50ms.

Filtro de paths excluidos:

tripwire_paths = [
    f for f in changed_files
    if not f.startswith(".github/scripts/bib_")
    and not f.startswith("scripts/harness/")
    and not f.startswith("context/")
]

Posición en el pipeline (antes del Tier 1):

commit → [TRIPWIRES] → Tier 1 pre-LLM → Tier 2 LLM → Tier 3 wiki actions

2. MCP bib_mark_verification_pending (workspace wiki.ts)

Handler que recibe { file_paths: string[], actor: string } y ejecuta:

UPDATE bib_wiki_pages
SET verification_pending = 1
WHERE sources LIKE '%"type":"code"%'
  AND sources LIKE '%"ref":"<path>"%'

Devuelve { marked: N, paths_processed: M }.

3. MCP bib_check_drift_for_doc (workspace wiki.ts, modelo Haiku 4.5)

Handler que recibe el slug de una página marcada y:

1. Recupera el contenido actual de la página wiki.
2. Lee el contenido actual del archivo fuente referenciado.
3. Usa Haiku 4.5 para analizar si hay drift real y qué secciones están desactualizadas.
4. Devuelve un informe estructurado de drift.

Coste estimado para el cron completo de drift: ~$2.4/mes.

Integración en el pipeline de ingest

# ── Tripwires (ADR knowledge-base-vs-graph Fase 2) ──
# Siempre antes del flow Tier 1/2/3: la marca verification_pending=1 ocurre
# independientemente de si el Ingest decide procesar o saltar el commit.
tripwire_result = trigger_tripwires(changed_files, mcp_token)
if tripwire_result.get("marked", 0) > 0:
    log(f"[Tripwire] Marked {tripwire_result['marked']} pages as verification_pending=1 "
        f"(paths checked: {tripwire_result.get('paths_processed', 0)})")
elif tripwire_result.get("error"):
    log(f"[Tripwire] ERROR: {tripwire_result['error']}")

Schema D1 relacionado (Fase 1, prerequisito)

La Fase 2 depende de los campos añadidos en la Fase 1 (PR workspace #36, D1 migration 0024):

Fases del ADR completo

Observabilidad

Logs emitidos por trigger_tripwires en cada ejecución del ingest:

• [Tripwire] Marked N pages as verification_pending=1 (paths checked: M) — operación normal.
• [Tripwire] ERROR: <mensaje> — fallo del MCP; el ingest continúa.
• Sin log — ningún path filtrado pasó el filtro de exclusión.

Véase también

• [[decision—20260514—kb-vs-graph-drift-detection]]