MCP Handler: bib_check_drift_for_doc

Descripción

Handler MCP implementado en functions/api/mcp/handlers/wiki.ts. Forma parte de la Pieza 3 del ADR KB vs Graph Fase 2.

Dado un slug de página wiki, recupera los commits que han tocado las sources de tipo code declaradas desde last_verified, le pide a Haiku 4.5 que audite si la documentación ha derivado (drift) respecto al código, y persiste el resultado en bib_drift_checks. Si hay drift confiable (confidence > 0.7), crea un draft de corrección para que el Curator lo triage.

Signatura

bib_check_drift_for_doc(slug: string, dry_run?: boolean) → DriftResult

Parámetros

Parámetro	Tipo	Requerido	Descripción
`slug`	`string`	Sí	Slug de la página wiki a auditar.
`dry_run`	`boolean`	No	Si `true`, no escribe en D1 ni crea drafts. Default: `false`.

Respuesta (drift detectado)

{
  "slug": "entity--racks--model--rack",
  "drift": true,
  "confidence": 0.85,
  "summary": "Campo rack_units renombrado en el modelo.",
  "suggested_changes_excerpt": "...",
  "draft_slug_created": "entity--racks--model--rack--drift-fix-20260514",
  "commits_total": 3,
  "commits_analyzed": 3,
  "haiku_input_tokens": 1240,
  "haiku_output_tokens": 187,
  "haiku_cost_usd": 0.00175,
  "dry_run": false
}

Respuesta (sin drift)

{
  "slug": "...",
  "drift": false,
  "confidence": 0.92,
  "summary": "Commits cosmetics only, no behavioral change.",
  "draft_slug_created": null,
  "commits_total": 1,
  "commits_analyzed": 1,
  "dry_run": false
}

Flujo detallado

bib_check_drift_for_doc(slug)
  ↓
  carga bib_wiki_pages (slug, title, type, sources, kind, lifecycle, last_verified, file_path)
  ↓
  filtra sources[type='code']  → si vacío: return {skipped: 'no_code_sources'}
  ↓
  GitHub Commits API ×cada source  (since=last_verified, per_page=5, cap=10 totales)
  ↓  si allCommits.length == 0:
        UPDATE last_verified=now, verification_pending=0
        INSERT bib_drift_checks (drift=0, confidence=0, 'no_commits_since_last_verified')
        → return {drift:false}
  ↓  si commits > 0:
        GitHub commit detail API ×top-5 (diff truncado 900 chars/archivo)
        fetchWikiBody(file_path)  → cuerpo .md sin front-matter, cap 6 KB
        callAnthropicHaiku(systemPrompt, userMessage, maxTokens=600)
        parseJsonFromLLM → {drift, confidence, summary, suggested_changes_excerpt}
  ↓
  drift && confidence>0.7 && !dry_run:
        wikiCreatePage(<slug>--drift-fix-YYYYMMDD, type=draft)
  ↓
  INSERT bib_drift_checks (todas las métricas)
  ↓
  (!drift || confidence<0.3) && !dry_run:
        UPDATE last_verified=now, verification_pending=0

Determinación del repositorio fuente

La función auxiliar repoForSourcePath(srcRef) decide qué repo usar para la GitHub Commits API:

Prefijo del `source.ref`	Repositorio
`functions/`, `src/`, `migrations/`, `scripts/`, `.github/workflows/wiki-`, `.github/workflows/cf-pages`, `.github/workflows/bib-reindex-ts`, `.github/workflows/drift-cron`, `.github/scripts/bib_ingest`, `public/supercontext/`	`CreaRackSL/CreaRackSL-workspace`
Cualquier otro	`CreaRackSL/CreaRack-Pro`

Draft generado por drift

Si drift=true && confidence>0.7, crea un draft con slug <original-slug>--drift-fix-YYYYMMDD con:

status: draft, owner: agent-drift-check
tags: ['drift-check', 'auto-generated', 'pending-review']
sources: [{type: 'doc', ref: slug}], related: [slug]
kind: knowledge_base, lifecycle: refresh-90d
Cuerpo: resumen del drift, cambios sugeridos, lista de commits, [[wikilink]] a la página original.

System prompt de Haiku

Haiku actúa como documentation drift auditor. Reglas de decisión clave:

Condición	Veredicto
Commits cosméticos (typos, comentarios, formateo, dep bumps no relacionados)	`drift=false, confidence≥0.8`
Commits cambian API, schema, flujo, comportamiento documentado	`drift=true, confidence≥0.7`
Intención del commit ambigua	`confidence ∈ (0.3, 0.7)` — no se crea draft

Tabla bib_drift_checks

Columna	Tipo	Descripción
`slug`	TEXT	Slug de la página auditada
`drift_detected`	INTEGER	0/1
`confidence`	REAL	0.0–1.0
`summary`	TEXT	Resumen en ≤500 chars
`draft_slug_created`	TEXT\|NULL	Slug del draft creado, si aplica
`haiku_input_tokens`	INTEGER	Tokens input facturados
`haiku_output_tokens`	INTEGER	Tokens output facturados
`haiku_cost_usd`	REAL	Coste en USD (Haiku 4.5 pricing)

Precios Haiku 4.5 (mid-2026)

$0.0008 / 1K input tokens
$0.004  / 1K output tokens

Calculados por la función auxiliar haikuCostUsd(inputTokens, outputTokens) definida en el mismo archivo.

Cambios en callAnthropicHaiku

A partir de este PR, callAnthropicHaiku devuelve { text, tokens, inputTokens, outputTokens } (antes solo text, tokens). El desglose inputTokens/outputTokens es necesario para el cálculo de coste diferenciado.

Véase también

[[feature—biblioteca—kb-vs-graph-fase2]] — feature que introduce este handler (Fase 2)
[[entity—biblioteca—handler—bib-mark-verification-pending]] — handler que marca las páginas que este audita
[[decision—20260514—knowledge-base-vs-graph]] — ADR origen
[[entity—biblioteca—handler—wiki-create-page]] — handler usado internamente para crear drafts de corrección
[[feature—biblioteca—kb-vs-graph-fase1]] — Fase 1 del mismo ADR