EXP-01: Recuperación de contexto de BE-02

Hipótesis relacionadas

H01 — El bundle incluye todos los recursos obligatorios.
H02 — El bundle excluye contenido irrelevante.
H03 — El bundle reduce el contexto.
H04 — El agente produce mejores resultados.

Pregunta

¿El bundle generado por get_task_context("BE-02") conserva todos los recursos obligatorios, excluye el contenido irrelevante y reduce el tamaño del contexto respecto de cargar toda la documentación?

Método

Ejecutar el servidor MCP (get_task_context y validate_traceability) sobre un repositorio demo.
Solicitar el contexto de la tarea objetivo.
Comparar el bundle contra el contexto monolítico (todos los documentos).
Medir las métricas de RES-03 (RES-03).
Registrar inclusiones/exclusiones y su justificación.

Comparadores:

#	Comparador	Descripción
1	Contexto completo	Carga todos los documentos del repo demo en el prompt (línea base monolítica)
2	Selección manual	Contexto montado a mano por el driver buscando los recursos BE-02
3	Bundle DocuGraph	Contexto devuelto por `get_task_context("BE-02")`

El comparador 4 (selección automática por heurística/embeddings) es opcional y se activa solo si resulta relevante según los hallazgos de la línea base (DEC-002, MASTER-00 v0.7 §5.2).

Preparación

Repositorio demo (DOC02): creado en research/evidence/demo-repo/ (MASTER-DEMO → US-DEMO-01 → BE-02, más IRRELEVANT-01 y BROKEN-LINK-DEMO) según los requisitos de GATE-0 §5. Fixtures de ciclo aislados en research/evidence/demo-repo-negatives/ (CYCLE-A/CYCLE-B).
Gold standard: definido en GOLD_STANDARD_BE-02.md antes de ejecutar el resolver (anti-circularidad, GATE-0 §5.2).
Fixtures: documentación de ejemplo con frontmatter e IDs estables según META-01.
Servidor MCP: implementado en :docugraph-mcp según MCP-G0 (STDIO; get_task_context + validate_traceability) sobre kotlin-sdk 0.15.0.

⚠️ Nota de identidad: el BE-02 de este experimento es una tarea del repositorio demo de Gate 0. No debe confundirse con BE-02 (spec de catálogo de producto, fase POST_MVP).

Métricas

Cobertura (§4.2), Precisión (§4.1), Omisión crítica (§4.3), Reducción de contexto (§4.4), tiempo de preparación de metadata y errores manuales (§4.5).

Criterio definido antes de ejecutar

Cobertura obligatoria: 100% (apoya H01).
Omisión crítica: 0% (apoya H01).
Reducción de contexto: positiva (apoya H03).
Precisión y calidad de implementación: medibles y comparables con el contexto monolítico (apoyan H02, H04).

El umbral mínimo de reducción se fijará tras obtener la línea base (TBD).

Resultados

Ejecutado el 2026-08-11 mediante una prueba de integración automatizada (docugraph-mcp:Exp01Gate0IntegrationTest) que conecta un cliente MCP real del SDK oficial (io.modelcontextprotocol:kotlin-sdk-client 0.15.0) contra el servidor real de :docugraph-mcp, con get_task_context y validate_traceability sirviendo el repositorio demo.

Criterio (§ Criterio definido antes de ejecutar)	Resultado	Apoya
Cobertura obligatoria 100%	100% — `BE-02`, `US-DEMO-01`, `MASTER-DEMO` presentes en el bundle	H01
Omisión crítica 0%	0% — ningún ID del gold standard §1 falta	H01
Precisión (sin irrelevantes)	100% — `IRRELEVANT-01`, `BROKEN-LINK-DEMO`, `CYCLE-A/B` ausentes del bundle	H02
Reducción de contexto	Positiva — bundle de 3 documentos vs. 6 documentos totales del workspace (`research/evidence/`); no incluye los 2 fixtures negativos ni el irrelevante	H03
Justificación por nodo	Presente — sección `## Inclusion report` con `depth` y razón (`root` / `depends_on from …`) por cada ID	MASTER-00 §5.1.4
`validate_traceability` sobre `research/evidence/`	`valid: false`; detecta `LINK_BROKEN_DEPENDS` (`BROKEN-LINK-DEMO → ID-QUE-NO-EXISTE`) y `LINK_CYCLE` (`CYCLE-A ↔ CYCLE-B`, vía Tarjan)	H01 (fail-closed)
`get_task_context` con `taskId` inexistente	Falla cerrado con `TASK_NOT_FOUND` (`isError = true`), no bundle parcial	GATE-0 §6 (done de servidor)
`maxDepth` truncado (prueba unitaria de `:docugraph-core`)	Con `maxDepth=1` el bundle se marca `truncated=true` y omite `MASTER-DEMO`	META-01 §7

Calidad de implementación por agentes (H04) y benchmark del Kotlin AI Benchmark (DEC-003 §punto 3): no evaluado en esta corrida — requiere un segundo agente consumiendo el bundle para comparar resultados frente al contexto monolítico; queda como próxima acción (ver abajo).

Evidencia

Repositorio demo: research/evidence/demo-repo/.
Fixtures negativos (ciclo): research/evidence/demo-repo-negatives/.
Gold standard pre-registrado: GOLD_STANDARD_BE-02.md.
Prueba de integración (cliente MCP real + servidor real, código fuente = log de evidencia reproducible): docugraph-mcp/src/test/kotlin/io/docugraph/mcp/Exp01Gate0IntegrationTest.kt.
Comando de reproducción: ./gradlew :docugraph-mcp:test :docugraph-core:test desde la raíz del monorepo (BUILD SUCCESSFUL, 15 pruebas, 0 fallos, verificado el 2026-08-11).
Servidor ejecutable de forma independiente vía ./gradlew :docugraph-mcp:run --args="--workspace <path>", mediante el launcher installDist (docugraph-mcp/build/install/docugraph-mcp/bin/docugraph-mcp.bat, con -Dkotlin-logging.logStartupMessage=false embebido) o la variable DOCUGRAPH_WORKSPACE.
Verificación externa §5.1.1 (2026-08-11): cliente MCP externo real (JetBrains Junie) spawneando el proceso STDIO docugraph-mcp.bat (installDist) con DOCUGRAPH_WORKSPACE=research/evidence/demo-repo -> 4/4 PASS: initialize correcto (serverInfo=docugraph-mcp), tools/list con las 2 tools, bundle de get_task_context("BE-02") exacto (sin IDs irrelevantes), validate_traceability("...research/evidence") -> valid:false con LINK_BROKEN_DEPENDS + LINK_CYCLE, y TASK_NOT_FOUND ante taskId inexistente. Cierra MASTER-00 §5.1.1; ver DEC-005.

Limitaciones

Cliente MCP no externo (RESUELTO 2026-08-11): la corrida automatizada validó MASTER-00 §5.1.1 con el Client oficial del SDK sobre transporte en memoria (ChannelTransport, módulo kotlin-sdk-testing) por restricción del entorno automatizado. Esa limitación quedó cerrada con un cliente MCP externo real (JetBrains Junie) vía proceso STDIO (docugraph-mcp.bat, installDist): 4/4 PASS (initialize, tools/list, bundle BE-02, validate_traceability, fail-closed). Detalle en DEC-005.
Alcance: una sola tarea (BE-02) y un solo repositorio demo sintético (5 documentos + 2 fixtures de ciclo aislados); no generaliza a otros dominios (ver caveat pre-registrado abajo).
H04 (calidad del agente) no evaluado: esta corrida mide el bundle en sí, no el resultado de un agente de IA implementando con y sin el bundle.
Reducción de contexto sin umbral numérico: se confirma dirección positiva (3 de 6 documentos), pero el umbral mínimo de aceptación sigue TBD (se fija con la línea base de PoC, fase B).

⚠️ Caveat pre-registrado (DEC-002, MASTER-00 §5.2): la evidencia de EXP-01 es específica de la tarea BE-02 del repositorio demo y no garantiza generalidad a otras tareas o repositorios. Las hipótesis H02/H03/H04 se interpretan como tendencias sobre este baseline, no como propiedades universales del mecanismo. Toda generalización requiere experimentos adicionales en otros dominios.

Decisión

CONTINUAR -> GATE 0 APROBADO (§15 de MASTER-00): los criterios definidos antes de ejecutar se cumplieron para el único caso de prueba disponible (cobertura 100%, omisión crítica 0%, precisión 100%, reducción de contexto positiva, justificación por nodo presente, fail-closed ante taskId inexistente y ante ciclos). El criterio §5.1.1 (cliente real) se cerró el 2026-08-11 con un cliente MCP externo real (JetBrains Junie) vía STDIO: 4/4 PASS (ver Limitaciones y DEC-005). Con esto se declara Gate 0 formalmente aprobado y queda habilitada la apertura de la Fase B (PoC).

Próxima acción

~~Verificar manualmente el handshake STDIO con un cliente MCP externo real (Junie, Claude Code o Cursor) invocando ./gradlew :docugraph-mcp:run --args="--workspace research/evidence/demo-repo"~~ HECHO (2026-08-11): JetBrains Junie (cliente externo) vía STDIO docugraph-mcp.bat (installDist) -> 4/4 PASS; criterio MASTER-00 §5.1.1 cerrado.
~~Registrar en DEC-LOG la aprobación formal de Gate 0~~ HECHO (2026-08-11): DEC-005 — Gate 0 formalmente aprobado.
Abierto:
1. Iniciar la Fase B (PoC, RES-00 §2) con 2 tareas adicionales para fijar el umbral de reducción de contexto y evaluar H04 con un agente real.
2. Registrar la salida del Gate 0 en RES-00 §7 y actualizar el checklist runtime de FIND-01 §3.

Registro de estado

Campo	Valor
Estado	COMPLETADA (GATE 0 APROBADO; §5.1.1 cerrado con cliente externo real)
Fecha de apertura	2026-08-05
Fecha de ejecución	2026-08-11
Fecha de cierre	2026-08-11
Cambio de estado en	DEC-LOG (`DEC-004`, `DEC-005`)