El Bibliotecario: los bots que mantienen el Supercontexto actualizado

Parte de la colección [[concept—workspace—supercontexto-00-vision]]. Cubre: el Ingest (qué hace en cada commit), el Curator (ciclo de vida de drafts), el Lint (detección de obsoletos), el reindex AST y el Informe Semanal.

¿Qué es el Bibliotecario?

El Bibliotecario es el conjunto de bots automáticos que mantienen el grafo y la wiki actualizados sin que nadie tenga que acordarse. No es un bot monolítico sino varios procesos especializados, cada uno con una misión concreta:

graph LR
    subgraph INGEST["📥 Ingest (en cada commit)"]
        I1["Lee el diff\ndel commit"]
        I2["Analiza con\nHaiku 4.5"]
        I3["Actualiza el grafo\n(nodos · edges)"]
        I4["Crea concept_page\nen status:draft"]
        I1 --> I2 --> I3
        I2 --> I4
    end

    subgraph CURATOR["🎭 Curator (L+J)"]
        C1["Revisa drafts\ncon ≥2 días de antigüedad"]
        C2["Haiku 4.5 decide:\npublicar / descartar"]
        C3["Si publica: status=published\nSi descarta: status=rejected"]
        C1 --> C2 --> C3
    end

    subgraph LINT["🔍 Lint (diario)"]
        L1["Detecta docs\ncon >60 días sin actualizar"]
        L2["Detecta huérfanas\n(sin código vinculado)"]
        L3["Detecta contradicciones\nentre páginas recientes"]
        L1 --> ALERTA["⚠️ Alerta en Pulse"]
        L2 --> ALERTA
        L3 --> ALERTA
    end

    COMMIT["🚀 git push"] --> INGEST
    NOCHE["🌙 Cada noche"] --> CURATOR
    NOCHE --> LINT

El Ingest: qué pasa en cada commit

Cada vez que hay un git push a main (en cualquiera de los dos repos), el workflow Bibliotecario-Ingest se dispara automáticamente.

Los pasos del Ingest

sequenceDiagram
    participant GH as GitHub Actions
    participant Script as bib_ingest.py
    participant LLM as Haiku 4.5
    participant MCP as MCP Server
    participant D1 as D1 Database

    GH->>Script: Lanza con PR_META + PR_DIFF
    Script->>Script: Parsea archivos modificados del commit
    Script->>LLM: "¿Qué conocimiento nuevo hay en este diff?"
    LLM-->>Script: JSON con nodos · edges · concept_pages propuestas
    Script->>MCP: bib_register_node() × N nodos nuevos
    Script->>MCP: bib_create_edge() × N relaciones nuevas
    Script->>MCP: wiki_create_page(type=concept_page, status=draft) si procede
    MCP->>D1: Persiste todo
    Note over Script: Si algo falla → abre issue automático en GitHub

¿Qué analiza el Ingest?

El Ingest analiza el diff del commit (qué líneas cambiaron en qué archivos) y le pregunta a Claude Haiku 4.5: “Con este cambio de código, ¿qué nodos del grafo hay que crear o actualizar? ¿Hay algún concepto nuevo que merezca una página en la wiki?”

Haiku devuelve un JSON estructurado con:

• Nodos nuevos o modificados (modelos, endpoints, funciones)
• Edges nuevos (relaciones entre artefactos)
• concept_page propuestas: páginas de conocimiento en borrador (status: draft)

¿Cuándo no se dispara el Ingest?

El Ingest no se dispara cuando:

• El commit es del propio Bibliotecario (empieza por wiki(...)) — evita bucles infinitos
• El commit lleva [skip ci] — aunque esto está casi prohibido por la Regla 16
• El workflow está pausado con BIBLIOTECARIO_PAUSADO=true

El Curator: quién decide qué se publica

El Curator es el bot que revisa los borradores (concept_pages en status draft) y decide si merecen publicarse o descartarse.

Ciclo de vida de una concept_page

stateDiagram-v2
    [*] --> draft: Ingest crea borrador
    draft --> published: Curator aprueba (calidad suficiente)
    draft --> rejected: Curator rechaza (redundante, incompleto, error)
    published --> archived: Código que describía ya no existe
    rejected --> [*]: Se elimina del repo
    archived --> [*]: Se mueve a archivo histórico

¿Qué criterios usa el Curator?

Haiku 4.5 evalúa cada borrador con preguntas como:

• ¿Aporta información que no está ya en otra página?
• ¿El contenido es suficientemente completo para ser útil?
• ¿El concepto que describe sigue siendo relevante en el código actual?

Si aprueba → status: published y la página aparece en la wiki.
Si rechaza → status: rejected y el borrador se elimina del repo.

Andamiaje de control (para depuración)

El script bib_ingest.py tiene variables de entorno para controlar el comportamiento en tests:

El Lint: detección de docs obsoletas

El Lint es el bot de higiene. Corre cada noche y busca tres tipos de problemas:

1. Páginas stale (obsoletas)

Una página se marca como stale si el código que describe no ha recibido ningún bib_report_change en los últimos 60 días. El umbral significa: “el código ha cambiado, pero nadie actualizó la doc”.

2. Páginas huérfanas

Una página es huérfana si no tiene ningún edge documents que la conecte a un nodo del grafo. Es documentación flotante sin código vinculado.

3. Contradicciones incrementales

El Lint compara el contenido de páginas “recientes” (modificadas en los últimos 7 días) con sus páginas relacionadas, buscando afirmaciones contradictorias. Por ejemplo: una página dice que el modelo tiene 5 campos, otra página sobre el mismo modelo dice que tiene 8.

El Lint de consolidación semanal

Además del lint diario (incremental), hay un lint de consolidación que corre los lunes. Este hace el pairwise completo: compara TODAS las páginas entre sí buscando contradicciones. Es más caro (en tokens y tiempo) pero cubre casos que el incremental no ve.

Los reindexadores AST

Además del Ingest semántico, hay dos procesos que extraen la estructura del código directamente (sin LLM, solo parseo sintáctico):

bib_ast.py — CreaRack-Pro (Python)

Corre en el servidor Hetzner Stage cada 6 horas. Usa el módulo ast de Python para extraer:

• Todas las clases y funciones del repo
• Sus parámetros, tipos y docstrings
• Las relaciones imports entre módulos

bib_ast_ts.mjs — Workspace (TypeScript)

Corre en GitHub Actions (diario a las 00:15 UTC, o en cada push que toca .ts/.tsx). Usa el compilador TypeScript para extraer la misma información de los archivos del workspace.

Ambos alimentan el mismo grafo D1. La combinación de AST (estructura) + Ingest semántico (significado) da el grafo más completo posible.

El Informe Semanal

Cada domingo a las 08:00 UTC, el bot Bibliotecario-Weekly-Report genera un informe en Markdown con el estado de la semana:

• Cuántos commits hubo en cada repo
• Cuántas concept_pages se crearon, publicaron y descartaron
• Qué docs siguen en estado stale
• Resumen de la salud del grafo

El informe se publica en public/supercontext/reports/weekly--YYYY-MM-DD.md del repo workspace y es accesible en workspace.crearack.com.

Cómo pausar todo el Bibliotecario

Si hay un momento en que conviene silenciar todos los bots (por ejemplo, un rebase masivo o una migración de estructura), hay un toggle global:

# Pausar
gh variable set BIBLIOTECARIO_PAUSADO --body true --repo CreaRackSL/CreaRackSL-workspace

# Reanudar
gh variable set BIBLIOTECARIO_PAUSADO --body false --repo CreaRackSL/CreaRackSL-workspace

Con BIBLIOTECARIO_PAUSADO=true, los workflows de Curator, Lint, Drift-check, Utility y bib-reindex-ts se saltan sus jobs sin consumir minutos de GitHub Actions.

Para Sync Cascade hay un toggle separado: SYNC_CASCADE_PAUSADO.

Véase también

• [[concept—workspace—supercontexto-00-vision]]
• [[concept—workspace—supercontexto-01-biblioteca]]
• [[concept—workspace—supercontexto-05-crons]]
• [[ia-tech—inventario-automatismos]]