Oráculo de EL — Fase 2: indexación del corpus claude-method en el Bibliotecario
Oráculo de EL — Fase 2: indexación del corpus claude-method en el Bibliotecario
Contexto
El Oráculo de EL es el asistente conversacional desplegado en workspace.crearack.com (s72). Hasta la Fase 2, el Oráculo tenía un gap significativo: los 49 documentos .md del repo privado CreaRackSL/claude-method (harness, biblioteca, agentes, design toolkit, onboarding, shared-memory, workflow, guides) nunca se habían indexado en el grafo bib_* del Bibliotecario. El resultado era que cualquier pregunta sobre el método del equipo quedaba sin grounding vectorial y el Oráculo respondía sin fuentes internas.
El PR#54 (sesión 73, Supercontexto Fase 9) cierra ese gap con dos artefactos: un script Node de extracción y un workflow CI de schedule diario.
Artefactos añadidos
scripts/bib_ingest_claude_method.mjs (~684 LOC)
Indexador Node.js que sigue el patrón de bib_ast_ts.mjs. Flujo en dos fases:
Phase A — bib_register_doc (secuencial, 1 por doc)
Registra cada .md en el grafo de la Biblioteca capturando su node_id. Se hace en serie —y no en batch— porque bib_index_docs (batch) no devuelve node_ids individuales que se necesitan para los chunks.
Phase B — bib_index_chunks (batch, lotes de 200)
Una vez obtenidos los node_ids de Phase A, acumula todos los chunks de todos los docs y los envía en una sola llamada batch. El handler interno los procesa en sublotes de 50.
Estrategia de chunking
| Condición | Acción |
|---|---|
| Doc completo < 800 palabras | Un único chunk |
| Doc ≥ 800 palabras | Splitear por secciones ## (H2) |
| Sección < 100 palabras | Acumular con la siguiente |
| Sección > 800 palabras | Sub-splitear por párrafos (\n\n) |
Constantes: CHUNK_MIN_WORDS=100, CHUNK_SOFT_MAX_WORDS=800.
Namespace D1
Todos los file_path llevan el prefijo claude-method/ (ej. claude-method/guides/QUICK_START.md) para evitar colisiones con docs del workspace que tienen rutas homónimas.
Derivación de metadatos
El script heurística category y doc_type a partir del path relativo:
| Path relativo | category | doc_type |
|---|---|---|
onboarding/shared-memory/* | onboarding-shared-memory | memory |
global-skills/* | global-skills | skill |
global-agents/*, agents/* | global-agents / agents | agent |
guides/* | guides | guide |
workflow/* | workflow | workflow |
biblioteca/* | biblioteca | reference |
harness/* | harness | reference |
templates/* | templates | template |
| raíz | root | doc |
CLI
# Solo stats sin push (dry-run)
node scripts/bib_ingest_claude_method.mjs --stats
# Push real contra MCP
node scripts/bib_ingest_claude_method.mjs --push --stats \
--mcp-url https://workspace.crearack.com/api/mcp \
--mcp-token $MCP_TOKEN
# Con root alternativo (dev local)
node scripts/bib_ingest_claude_method.mjs --push --stats --root ../claude-method
# Dump payload para debug (sin push)
node scripts/bib_ingest_claude_method.mjs --output /tmp/cm-payload.jsonEl toggle global BIBLIOTECARIO_PAUSADO=true (variable de repositorio) aborta el script antes de cualquier llamada MCP — mismo mecanismo que el resto de crons del Bibliotecario.
.github/workflows/bib-reindex-claude-method.yml (66 LOC)
| Campo | Valor |
|---|---|
| Nombre | Bibliotecario-Reindex-ClaudeMethod |
| Schedule | 30 0 * * * (00:30 UTC diario) |
| Trigger manual | workflow_dispatch |
| Runner | ubuntu-latest, timeout 10 min |
| Concurrency | bib-reindex-claude-method-${{ github.ref }}, cancel-in-progress |
| Toggle pausa | vars.BIBLIOTECARIO_PAUSADO != 'true' |
El horario 00:30 está elegido para evitar colisión con bib-reindex-ts (00:15 UTC) y el cron Python de Hetzner (cada 6h). El repo claude-method es externo a este workspace — se clona con --depth 1 en cada run vía deploy key SSH dedicada.
Pasos del job reindex
checkout@v6del workspace (fetch-depth 1).ssh-agent@v0.9.0consecrets.CLAUDE_METHOD_DEPLOY_KEY.git clone --depth 1 git@github.com:CreaRackSL/claude-method.git external/claude-method.setup-node@v6(Node 20).node scripts/bib_ingest_claude_method.mjs --push --stats --root external/claude-method.
Variables de entorno requeridas: BIB_MCP_URL, BIB_MCP_TOKEN, CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET.
Auth: deploy key SSH (no PAT Fine-grained)
Decisión adoptada para el acceso de lectura al repo privado claude-method:
| Criterio | Deploy Key SSH | PAT Fine-grained |
|---|---|---|
| Scope | 1 repo, read-only | Multi-repo por diseño |
| Caducidad | No expira | Máx 1 año |
| Bus factor | No atado a cuenta personal | Atado al owner del PAT |
| Creación | gh api (self-service) | Requiere UI web |
- Pubkey registrada en
CreaRackSL/claude-method/settings/keys(id151959707, verified). - Privkey en
secrets.CLAUDE_METHOD_DEPLOY_KEYdel workspace.
Volumen esperado tras bootstrap
| Métrica | Estimación |
|---|---|
Docs .md descubiertos | ~49 |
| Docs registrados (Phase A) | ~49 |
| Chunks indexados (Phase B) | ~80–150 |
Plan de validación post-merge
gh workflow run bib-reindex-claude-method.yml(bootstrap inmediato).- Validar logs CI: ~49 docs Phase A + ~80-150 chunks Phase B.
- Smoke test en Oráculo (
workspace.crearack.com): preguntar sobre método del equipo (ej. “¿qué es design-collaborator?”, “¿cómo funciona el harness pre-commit?”). - Confirmar
relevance > 0.4en matches → Oráculo responde con grounding declaude-method.
Idempotencia
El script es seguro para re-ejecución. bib_register_doc y bib_index_chunks usan content_hash para detectar docs/chunks sin cambios y devolverlos como skipped. En un segundo run con docs sin modificar, Phase B reportará chunks_created=0, chunks_updated=0, chunks_skipped=N sin error.
Véase también
- [[entity—biblioteca—doc—bib-register-doc]]
- [[entity—biblioteca—doc—bib-index-chunks]]
- [[concept—biblioteca—corpus-indexing]]
- [[runbook—biblioteca—reindex-claude-method]]
- [[feature—biblioteca—oraculo-fase-1]]