Protocolo de evaluación anti-sesgo de H04: calidad de implementación con bundle vs. contexto monolítico (get_dependency_graph)

Protocolo de evaluación anti-sesgo — H04 / EXP-05 (get_dependency_graph)

Regla anti-sesgo (obligatoria, MASTER-00 §0.1/§14, RES-03 “Regla anti sesgo”): este documento se escribe y se aprueba antes de ejecutar cualquier corrida con agentes de IA. Ninguno de los criterios, comparadores o métricas definidos aquí puede modificarse después de conocer un resultado sin registrar el cambio y su justificación en DEC-LOG. Los resultados negativos (H04 no apoyada) se documentan igual que los positivos y no se reinterpretan.

0. Objetivo

Evaluar la hipótesis H04 (“el agente produce mejores resultados con el bundle de DocuGraph; menos incumplimientos respecto de la spec”, RES-02 §H04, RQ04) con una tarea real de implementación, siguiendo la metodología de datasets/evaluación del Kotlin AI Benchmark de JetBrains (DEC-003 §3, RES-03 §4.6): comparar la calidad de la implementación producida por un agente de IA cuando recibe el bundle de DocuGraph (get_task_context) frente a cuando recibe el contexto monolítico (todo docs/), para la misma tarea de implementación.

a) Enunciado exacto de la tarea a implementar

Implementar la tool MCP get_dependency_graph(nodeId, depth) — ítem P1 del PoC (GATE_0_SPEC §7, no incluida en el alcance de Gate 0, §2) — en :docugraph-core (lógica de grafo, sin dependencias de UI/SO, regla KMP DEC-002) y :docugraph-mcp (registro de la tool sobre kotlin-sdk, solo adaptación de transporte/I-O), con pruebas automatizadas (unitarias en :docugraph-core e integración con cliente MCP real en :docugraph-mcp, análogas a las de get_task_context/validate_traceability).

Esta redacción es literal a la entrada de la tarea (Fase B — EXP-05 / H04) y es el enunciado que se entrega sin modificación a ambos grupos del experimento (§4); solo cambia el contexto adjunto (bundle vs. monolítico, §4.2).

b) Criterios de aceptación

Fuente primaria citada por la tarea: MCP-SPEC §4.2. Se combinan con el resto de fuentes del catálogo que describen la misma tool, y se registra explícitamente la discrepancia encontrada entre ellas (§c), en lugar de resolverla implícitamente, para no introducir un criterio de aceptación ambiguo a mitad del experimento.

#	Criterio	Fuente
1	La tool se registra en :docugraph-mcp con nombre get_dependency_graph, descubrible vía tools/list (JSON-RPC)	MCP-SPEC §4
2	Firma de parámetros: nodeId: String (requerido) y depth: Int (opcional, default 3)	Enunciado (a); tabla de herramientas MCP de AGENTS.md §“MCP Server Integration & Tool Matrix”
3	Retorna JSON (estructura de grafo/lista de adyacencia) con dependencias ascendentes (depends_on) y descendentes (depended_by) de nodeId, acotadas a depth saltos	AGENTS.md (ídem fila 2); ARCH-03 §2.1.4 (motor de pruning/límite de profundidad ya existente para get_task_context, reutilizable)
4	Ejecución determinista: misma entrada (nodeId, depth, mismo workspace) produce siempre el mismo JSON	GATE-0 §4, criterio 5 (“la ejecución es reproducible”), aplicado por analogía
5	Fail-closed ante nodeId inexistente: error tipado (análogo a TASK_NOT_FOUND de get_task_context), no un grafo parcial ni una excepción no controlada	GATE-0 §6 (“done de implementación”), por analogía con get_task_context
6	La lógica de traversal/grafo vive en :docugraph-core; :docugraph-mcp solo adapta transporte (Regla “Monorepo Boundaries” de AGENTS.md)	AGENTS.md §“Monorepo Boundaries & Safe Zones”
7	Cobertura de pruebas: ≥1 test unitario en :docugraph-core (incluye caso con ciclo y caso con depth truncado) y ≥1 test de integración en :docugraph-mcp con cliente MCP real	GATE-0 §6; patrón ya usado en Exp01Gate0IntegrationTest
8	./gradlew :docugraph-core:test :docugraph-mcp:test en verde (BUILD SUCCESSFUL, 0 fallos) tras el cambio	GATE-0 §6, criterio de reproducibilidad
9	No se duplican DTOs/esquemas ya definidos para get_task_context/validate_traceability; se reutiliza el modelo de grafo existente en :docugraph-core	Regla 4 de AGENTS.md (cero duplicación)
10	Si el agente implementa en su lugar (o adicionalmente) la firma get_dependency_graph(workspacePath) de MCP-SPEC §4.2 / docs/03_ARCHITECTURE.md §2.3 sin declarar explícitamente la discrepancia de §c, se registra como incumplimiento de spec (RES-03 §4.6, “reglas de negocio omitidas”)	Este documento (criterio de desambiguación, fijado antes de la corrida)

c) Discrepancia de contrato detectada (transparencia obligatoria, anti-sesgo)

Al preparar este protocolo se detectó que tres fuentes del repositorio describen firmas distintas para get_dependency_graph, y ninguna corrida se ejecuta hasta dejarlo registrado:

Fuente	Firma declarada	Retorno
AGENTS.md §“Tool Matrix”	nodeId: String, depth: Int = 3	JSON (Graph Tree): adyacencia ascendente/descendente desde nodeId
MCP-SPEC §4.2	workspacePath: String? (opcional)	Grafo completo del workspace (adjacency list); delega en BE-03 buildGraph
ARCH-03 §2.3	workspacePath: String	Igual a MCP-SPEC §4.2 (réplica)

El enunciado de la tarea (a) exige explícitamente get_dependency_graph(nodeId, depth), que coincide con AGENTS.md y no con MCP-SPEC §4.2/ARCH-03. Se adopta como contrato vigente de este experimento la firma nodeId/depth (AGENTS.md), por ser la única que permite acotar nodo de partida y profundidad —análoga a get_task_context— y por ser la firma citada literalmente en el enunciado de la tarea. Esto no resuelve la inconsistencia documental de forma definitiva: queda como acción pendiente (§7) actualizar MCP-SPEC §4.2 y ARCH-03 §2.3, o registrar una decisión formal en DEC-LOG que unifique ambas firmas, fuera del alcance de este protocolo de evaluación.

1. Diseño experimental

Metodología alineada con el Kotlin AI Benchmark (DEC-003 §3): tarea real, agente de IA, comparación de calidad de implementación contra criterios de aceptación fijados de antemano (§b), no contra una impresión subjetiva post-hoc.

1.1 Grupos (comparadores, análogo a EXP-01 §Método)

Grupo	Contexto entregado al agente	Descripción
Control (monolítico)	Todo docs/ cargado en el prompt (36 documentos, contexto completo, línea base ya medida en EXP-03/EXP-04)	Sin filtrado automático
Tratamiento (bundle DocuGraph)	Salida de get_task_context("MCP-SPEC") sobre DOCUGRAPH_WORKSPACE=docs (bundle acotado a la cadena depends_on de MCP-SPEC: [US-04, US-05, BE-04, BE-05] y sus upstream transitivos — incluye la spec de la tool MCP-SPEC §4.2 y los precedentes de implementación BE-04/BE-05)	Contexto filtrado y justificado por nodo (## Inclusion report)

Se elige MCP-SPEC como raíz del bundle porque la spec de la tool a implementar vive en MCP-SPEC §4.2 y get_task_context sigue la cadena depends_on hacia arriba: un bundle con raíz BE-03 no incluiría MCP-SPEC ni los precedentes BE-04/BE-05 (la delegación “delega en BE-03 buildGraph” se refiere al backend de la operación, no al enlace de dependencia documental) y privaría al grupo tratamiento del contrato exacto de la tool. Con raíz MCP-SPEC el bundle entrega la spec + los ejemplos de las otras dos tools (análogo al rol de BE-04 en EXP-03). Corrección de diseño pre-corrida (2026-08-11, tras revisión del protocolo, con 0 corridas ejecutadas): no afecta criterios de §b ni métricas de §2.

Ambos grupos reciben exactamente el mismo enunciado (a) y el mismo repositorio de trabajo (el monorepo real, no un fixture sintético). No se revela a ningún agente qué grupo está evaluando ni la hipótesis H04, para evitar sesgo de expectativa.

1.2 Repeticiones

Dado que el objetivo es research/validación técnica (no un producto comprometido, ver AGENTS.md “Research & Validation Zone”), se ejecuta 1 corrida por grupo en esta primera pasada (n=1×2, análogo al alcance de EXP-01/EXP-03). La limitación de tamaño de muestra se declara explícitamente como hallazgo (no como generalización) en el informe final del experimento, igual que el caveat pre-registrado de EXP-01.

2. Métricas (RES-03 §4.6, alineadas a Kotlin AI Benchmark)

Para cada grupo, sobre la implementación final entregada por el agente:

1. Criterios de aceptación cumplidos — cuántos de los 10 ítems de §b se cumplen (recuento y %).
2. Errores de contrato — desviaciones respecto de §b (p. ej. firma incorrecta, retorno no determinista, ausencia de fail-closed).
3. Reglas de negocio omitidas — p. ej. no reutilizar el motor de pruning existente, duplicar DTOs (criterio 9).
4. Archivos modificados fuera de alcance — cambios fuera de :docugraph-core/:docugraph-mcp (viola “Monorepo Boundaries” de AGENTS.md).
5. Correcciones manuales necesarias — intervenciones humanas para que el código compile o pase pruebas, tras la entrega del agente.
6. Pruebas aprobadas — resultado de ./gradlew :docugraph-core:test :docugraph-mcp:test (número de pruebas, fallos, y si el agente escribió las pruebas exigidas por el criterio 7).

Todas las métricas se registran por grupo en una tabla comparativa en el documento de resultados de EXP-05 (a crear tras esta corrida), siguiendo el formato de tabla “Criterio → Resultado → Apoya” usado en EXP-01/EXP-03/EXP-04.

3. Procedimiento de ejecución (orden fijo, no negociable tras iniciar)

1. Congelar este documento (commit) antes de invocar ningún agente.
2. Grupo control: entregar enunciado (a) + contexto monolítico de docs/; registrar el diff/PR producido, sin revelar los criterios de §b al agente evaluado.
3. Grupo tratamiento: ejecutar get_task_context("MCP-SPEC") sobre DOCUGRAPH_WORKSPACE=docs, guardar el bundle crudo en research/evidence/bundle_MCP-SPEC_h04_raw.md (evidencia reproducible, mismo patrón que bundle_BE-04_real_raw.md); entregar enunciado (a) + ese bundle al agente evaluado.
4. Para cada grupo, correr ./gradlew :docugraph-core:test :docugraph-mcp:test sobre el resultado y registrar salida completa como evidencia.
5. Un revisor (humano o agente distinto del evaluado) aplica la checklist de §b a cada implementación sin conocer a qué grupo perteneció el resultado que está calificando (ciego simple, mitiga sesgo de confirmación de H04).
6. Consolidar métricas de §2 en el documento de resultados EXP-05 y decidir el veredicto de H04 (APOYADA / REFUTADA / INCONCLUSA) según el criterio de §15 de MASTER-00, registrando el cambio de estado en DEC-LOG.

4. Reglas anti-sesgo aplicables (resumen operativo)

• No se modifica el enunciado (a), los criterios (b) ni las métricas (§2) después de ver cualquier resultado parcial (RES-03 “Regla anti sesgo”).
• La discrepancia de contrato (§c) se registra antes de la corrida, no se “arregla” en silencio eligiendo la interpretación que favorezca a un grupo.
• El revisor de la checklist de §b actúa a ciegas respecto del grupo (§3.5).
• Un resultado donde H04 no se apoye (p. ej. ambos grupos cumplen igual número de criterios, o el bundle produce peor resultado) se documenta igual que un resultado positivo, sin reinterpretación posterior (MASTER-00 §0.1/§14).
• Alcance declarado: n=1×2, una sola tarea (get_dependency_graph) y un solo repositorio (el monorepo real de DocuGraph); no se generaliza a otras tareas/dominios sin evidencia adicional, igual que el caveat pre-registrado de EXP-01.

5. Trazabilidad

• Hipótesis evaluada: H04 (RES-02), pregunta RQ04 (RES-01).
• Métricas: RES-03 §4.6, alineadas a DEC-003 (Kotlin AI Benchmark).
• Especificación de la tool: MCP-SPEC §4.2; réplica en ARCH-03 §2.3; alcance P1 del PoC en GATE-0 §7.
• Precedente metodológico: EXP-01, EXP-03, EXP-04.
• Este documento no constituye el experimento EXP-05 en sí; es el pre-registro anti-sesgo (Paso 0) exigido antes de iniciar cualquier corrida. El experimento EXP-05 se crea como documento aparte una vez ejecutado el procedimiento de §3, y entonces se añade a depended_by de este documento.

6. Registro de estado

Campo	Valor
Estado	Protocolo APROBADO (pre-registro); ninguna corrida ejecutada aún
Fecha de creación	2026-08-11
Corridas ejecutadas	0
Próxima acción	Ejecutar §3 (Procedimiento de ejecución) y crear research/experiments/EXP-05_calidad_implementacion_h04.md con los resultados