Oráculo de EL · Fase 2 — Indexación de claude-method en el Bibliotecario

Oráculo de EL · Fase 2 — Indexación de claude-method en el Bibliotecario

Contexto

El Oráculo de EL es el sistema de consulta inteligente del equipo CreaRack que permite a los agentes Claude responder preguntas sobre el propio proyecto usando el grafo de conocimiento del Bibliotecario. Hasta la Fase 2 (sesión 73, Supercontexto Fase 9), el Oráculo carecía de acceso al método del equipo: los 49 documentos .md del repositorio privado CreaRackSL/claude-method nunca habían sido indexados en el corpus bib_*.

Este gap impedía que el Oráculo respondiera sobre:

• El harness de trabajo con Claude
• La biblioteca de prompts y referencias
• Los agentes globales del equipo
• El design toolkit y global-skills
• El onboarding y la shared-memory de footguns
• El workflow y las plantillas de sesión

La Fase 2 cierra este gap completamente.

Qué se implementó

1. Script indexador — bib_ingest_claude_method.mjs

Nuevo script Node.js (~684 LOC) en scripts/ que implementa un pipeline de dos fases para registrar los docs de claude-method en el corpus del Bibliotecario:

El script usa bib_register_doc en serie (no el batch bib_index_docs) porque éste no devuelve node_id individuales, necesarios para enlazar los chunks.

Lógica de chunking

El chunker implementa una estrategia adaptativa sobre H2 (##):

• Docs < 800 palabras → un único chunk
• Docs > 800 palabras → split por secciones H2
  • Secciones pequeñas (< 100 palabras) se fusionan con la siguiente
  • Secciones grandes (> 800 palabras) se sub-splitean por párrafos

Namespace y categorías

Todos los file_path llevan el prefijo claude-method/ para evitar colisiones con docs del workspace (p.ej. guides/QUICK_START.md existe en ambos repos).

Las categorías derivadas automáticamente:

2. Workflow CI — bib-reindex-claude-method.yml

Nuevo GitHub Actions workflow que automatiza la re-indexación diaria:

• Schedule: cron: "30 0 * * *" (00:30 UTC) — evita colisión con bib-reindex-ts (00:15)
• Trigger manual: workflow_dispatch
• Acceso SSH: usa secret CLAUDE_METHOD_DEPLOY_KEY (deploy key SSH read-only en CreaRackSL/claude-method)
• Toggle global: respeta BIBLIOTECARIO_PAUSADO != 'true' (misma variable que Curator/Lint/Utility/Drift-check)
• Runtime: Node 20, timeout 10 min

Flujo del job reindex:

1. Checkout workspace
2. Setup SSH agent con deploy key
3. git clone --depth 1 git@github.com:CreaRackSL/claude-method.git external/claude-method
4. Setup Node 20
5. node scripts/bib_ingest_claude_method.mjs --push --stats --root external/claude-method

3. Secretos requeridos

Uso local (desarrollo)

# Dry-run con stats (sin push)
node scripts/bib_ingest_claude_method.mjs --stats --root ../claude-method

# Push real al Bibliotecario
node scripts/bib_ingest_claude_method.mjs --push --stats \
  --mcp-url https://workspace.crearack.com/api/mcp \
  --mcp-token $MCP_TOKEN \
  --root ../claude-method

# Volcar payload debug a JSON (sin push)
node scripts/bib_ingest_claude_method.mjs --output /tmp/cm-payload.json --root ../claude-method

Diseño defensivo (Regla 15)

El script implementa múltiples guards contra fallos silenciosos:

• HTTP 200 ≠ éxito: inspecciona data.error y inner.errors por separado
• Phase A: si registra 0 docs con docs_total > 0 → process.exit(3) (no continúa Phase B con datos inválidos)
• Phase A parcial: avisa por stderr pero continúa (no aborta por docs individuales que fallan)
• Phase B: detecta 0 cambios aceptados con chunks > 0 (posible 2º run idempotente o schema mismatch)

Alcance

• 49 archivos .md del repo claude-method
• Los 3 archivos .ts del repo se ignoran (ya cubiertos por bib_ast_ts)
• No hay push trigger desde claude-method — el cron diario garantiza frescura

Referencias de sesión

• Sesión: 73
• Oráculo de EL: Fase 2
• Supercontexto: Fase 9
• PR: #54 — edu/oraculo-fase2-claude-method

Véase también

• [[entity—scripts—service—bib-ingest-claude-method]]
• [[entity—ci—workflow—bib-ingest-claude-method]]