CreaRack-SL

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

Vista limpiaEditar
Funcionalidadactivecreado Tue May 19#oraculo#biblioteca#supercontext#ci#infra#claude-method#indexacion#supercontext-fase-9

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:

FaseTool MCP usadaDescripción
Phase Abib_register_docRegistra cada doc individualmente (secuencial) para obtener node_id
Phase Bbib_index_chunksIndexa todos los chunks en batch (lotes de 200) con los node_id capturados en Phase A

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:

Path prefixCategoríadoc_type
onboarding/shared-memory/onboarding-shared-memorymemory
global-skills/global-skillsskill
global-agents/global-agentsagent
agents/agentsagent
guides/guidesguide
workflow/workflowworkflow
biblioteca/bibliotecareference
harness/harnessreference
templates/templatestemplate
onboarding/onboardingguide
raízrootdoc

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

SecretDescripción
CLAUDE_METHOD_DEPLOY_KEYSSH private key read-only para clonar claude-method
MCP_TOKENBearer token para el endpoint MCP del Bibliotecario
CF_ACCESS_CLIENT_IDCloudflare Access client ID
CF_ACCESS_CLIENT_SECRETCloudflare Access client secret

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]]

Referenciado desde

Inicio
Yo