EXP-03: validación del umbral con tarea real del catálogo (BE-04)

EXP-03: validación del umbral con tarea real del catálogo (Fase B)

Hipótesis relacionadas

• H01 — El bundle incluye todos los recursos obligatorios.
• H02 — El bundle excluye contenido irrelevante.
• H03 — El bundle reduce el contexto.

Pregunta

¿Se sostiene el umbral provisional de reducción de contexto ≥40% (DEC-006) al ejecutar get_task_context sobre una tarea real de docs/backend/, con la documentación real del catálogo de producto en lugar de fixtures sintéticos del repositorio demo?

Método

1. Elegir una tarea real de docs/backend/ cuya cadena depends_on se resuelva (mayormente) dentro de docs/, verificando primero qué nodos upstream citados quedan fuera del workspace.
2. Pre-registrar el gold standard manualmente en research/evidence/GOLD_STANDARD_BE-04_REAL.md antes de ejecutar el resolver (anti-circularidad, GATE-0 §5.2).
3. Configurar DOCUGRAPH_WORKSPACE=<repo>\docs e invocar get_task_context(taskId) con un cliente MCP externo mínimo hablando JSON-RPC 2.0 delimitado por saltos de línea sobre el proceso STDIO real (docugraph-mcp.bat, sin modificar :docugraph-core ni :docugraph-mcp).
4. Medir cobertura, precisión y omisión crítica contra el gold standard, y reducción de contexto con la heurística caracteres/4 (igual que EXP-02), usando dos comparadores: la cadena de documentos de la tarea y el contexto completo de docs/.
5. Emitir veredicto sobre el umbral de DEC-006.

Comparadores:

#	Comparador	Descripción
1	Cadena de la tarea	Los 11 documentos reales de docs/ que forman la cadena depends_on de BE-04
2	Contexto completo de docs/	Los 36 documentos Markdown/YAML reales de docs/ (catálogo completo de producto)
3	Bundle DocuGraph	Contexto devuelto por get_task_context("BE-04") sobre docs/ real

Preparación

• Tarea elegida: BE-04 (docs/backend/BE-04_mcp.get_task_context.md), preferida sobre BE-02 por tener una cadena depends_on más profunda y con bifurcaciones (vía SCHEMA-01 e IX-04), un caso más exigente que una cadena lineal.
• Nodos upstream fuera del workspace docs/ (excluidos del gold con justificación): AGENTS (AGENTS.md, raíz del repo) y README (README.md, raíz del repo). Ambos son citados en depends_on de la cadena pero no tienen archivo dentro de docs/; ver §0 de GOLD_STANDARD_BE-04_REAL.md.
• Gold standard: GOLD_STANDARD_BE-04_REAL.md, pre-registrado por lectura manual de docs/backend/BE-04_mcp.get_task_context.md y su cadena depends_on transitiva, antes de ejecutar el resolver.
• Servidor MCP: mismo binario de Gate 0 (:docugraph-mcp, installDist), sin modificaciones de código (no se tocó :docugraph-core ni :docugraph-mcp para este experimento).
• Cliente MCP: script externo mínimo JSON-RPC 2.0 sobre STDIO (research/evidence/mcp_client_exp03.ps1), reproduciendo el mismo transporte de EXP-01/EXP-02.
• Workspace: DOCUGRAPH_WORKSPACE=C:\Users\mclev\Documents\GitHub\docugraph\docs (catálogo de producto real, no research/evidence/demo-repo/).

Resultados

Ejecutado el 2026-08-11 contra el servidor real (installDist) vía STDIO, con DOCUGRAPH_WORKSPACE=docs.

Cobertura, precisión y omisión crítica (RES-03 §4.1–4.3)

## Inclusion report del bundle real (research/evidence/bundle_BE-04_real_raw.md):

- `BE-04` depth=0: root
- `SCHEMA-01` depth=1: depends_on from BE-04
- `IX-04` depth=1: depends_on from BE-04
- `US-06` depth=2: depends_on from IX-04
- `US-05` depth=2: depends_on from IX-04
- `US-04` depth=1: depends_on from BE-04
- `US-03` depth=2: depends_on from SCHEMA-01
- `US-02` depth=2: depends_on from SCHEMA-01
- `US-01` depth=2: depends_on from SCHEMA-01
- `VISION-00` depth=2: depends_on from IX-04
- `MASTER-00` depth=3: depends_on from VISION-00

Métrica	Resultado
Recursos obligatorios (gold, §1 de GOLD_STANDARD_BE-04_REAL.md)	11 (BE-04, SCHEMA-01, IX-04, US-01..06, VISION-00, MASTER-00)
Presentes en el bundle real	11/11
Cobertura	100%
Recursos irrelevantes o de otras cadenas presentes (§3 del gold)	0 (ningún BE-0{1,2,3,5,6}, FE-0X, IX-0{1,2,3}, etc.)
Precisión	100%
AGENTS/README en el bundle	0 (correctamente omitidos: el resolver los excluye en silencio por no existir dentro de docs/, sin error)
Omisión crítica	0%

El bundle real coincide exactamente, nodo por nodo, con la predicción manual del gold standard §1 (sin falsos positivos ni falsos negativos). Apoya H01 y H02 también fuera del repositorio demo.

Reducción de contexto (RES-03 §4.4)

Tamaños medidos con Get-Content -Raw (caracteres reales de archivo) y aproximación de tokens ÷4 (heurística estándar, igual que EXP-02; limitación documentada):

Comparador	Caracteres	Tokens≈ (÷4)
Bundle real (get_task_context("BE-04"))	112 250	~28 062
Cadena de la tarea (11 documentos reales de docs/)	110 455	~27 614
Contexto completo de docs/ (36 documentos)	376 433	~94 108

Comparación	Reducción 1 - bundle/comparador
Bundle vs. cadena de la tarea	-1.63% (el bundle es ligeramente mayor que la suma cruda de los 11 documentos)
Bundle vs. contexto completo de docs/	70.17%

Hallazgo clave: para esta tarea real, la cadena depends_on obligatoria (11 documentos) ya representa un subconjunto muy concentrado y grande dentro de sí misma (MASTER-00 solo aporta 31 919 caracteres, más de la cuarta parte de la cadena). El renderizado del bundle (encabezados ### id — título, línea path:, sección ## Inclusion report) añade ~1 795 caracteres de overhead sobre la simple concatenación de los 11 archivos fuente, por lo que la reducción vs. la cadena es ligeramente negativa: el bundle no comprime el texto de cada documento, solo filtra qué documentos incluir. La reducción real y sustancial proviene de filtrar 11 de 36 documentos del catálogo (bundle vs. contexto completo de docs/): 70.17%, muy por encima del umbral provisional de DEC-006.

get_task_context con taskId real fuera de la cadena

No se repitió la prueba negativa TASK_NOT_FOUND (ya cubierta en EXP-01/EXP-02 sin necesidad de repetición, Regla 4 de AGENTS.md); se ejecutó validate_traceability(workspacePath="docs") en su lugar, ver Evidencia.

validate_traceability sobre docs/ (confirma §0 del gold standard)

nodeCount=35, edgeCount=154, valid=false (research/evidence/validate_traceability_docs_raw.json). Entre los LINK_BROKEN_DEPENDS reportados están, exactamente los previstos en §0 del gold standard:

• 'BE-04' depende de 'AGENTS', que no existe en el workspace
• 'IX-04' depende de 'AGENTS', que no existe en el workspace
• 'US-04' depende de 'AGENTS', que no existe en el workspace
• 'US-05' depende de 'AGENTS', que no existe en el workspace
• 'VISION-00' depende de 'README', que no existe en el workspace

Confirma, de forma independiente al bundle, que AGENTS/README están correctamente excluidos del gold por no existir dentro de docs/, y que el resolver de get_task_context los omite en silencio en el bundle (sin listarlos en ## Inclusion report) exactamente por este motivo. nodeCount=35 (no 36) porque docs/api/openapi.yaml no tiene frontmatter YAML de DocuGraph parseable por validate_traceability, aunque sí se contó en el total de caracteres del comparador “contexto completo de docs/” (§ Reducción de contexto); diferencia irrelevante para la medición de reducción (1 archivo de 36, impacto marginal en caracteres).

Informe de validación del umbral

• Cobertura obligatoria: 100% (11/11 recursos del gold presentes). Apoya H01, ahora también con documentación real de producto.
• Omisión crítica: 0%. Apoya H01.
• Precisión: 100% (0 recursos irrelevantes o de otras cadenas). Apoya H02.
• Reducción de contexto vs. contexto completo de docs/: 70.17%, muy por encima del umbral provisional ≥40% de DEC-006. Apoya H03.
• Reducción de contexto vs. la cadena de la tarea: -1.63% (negativa/nula) — hallazgo nuevo no observado en EXP-02 (los fixtures sintéticos no medían este comparador porque el repositorio demo completo era casi la cadena). No refuta H03 (el comparador oficial de DEC-006/RES-03 §4.4 es “bundle vs. contexto completo”), pero matiza su interpretación: el valor del resolver frente a copiar y pegar manualmente los documentos correctos no es “comprimir” cada documento, sino identificar con precisión el subconjunto correcto (11 de 36) sin intervención humana ni riesgo de omisión/inclusión errónea.

Veredicto sobre el umbral (DEC-006)

El umbral provisional ≥40% se sostiene con una tarea real del catálogo de producto: 70.17% ≥ 40%. No se requiere un ajuste del umbral (no se abre DEC-007 como cambio de valor); en su lugar se registra DEC-007 como confirmación del umbral con evidencia real, cerrando la revisión pendiente anotada en DEC-006 (“Fecha de revisión: antes de declarar el criterio §5.2 de MASTER-00 cumplido para MVP, con evidencia de al menos una tarea real”).

Evidencia

• Gold standard pre-registrado: GOLD_STANDARD_BE-04_REAL.md.
• Bundle real capturado: research/evidence/bundle_BE-04_real_raw.md (112 250 caracteres).
• Reporte de validate_traceability("docs"): research/evidence/validate_traceability_docs_raw.json.
• Sesión JSON-RPC completa (initialize, tools/list, get_task_context("BE-04"), validate_traceability): research/evidence/mcp_raw_exp03.json.
• Cliente usado: research/evidence/mcp_client_exp03.ps1 (script externo mínimo JSON-RPC 2.0 sobre STDIO; no forma parte de :docugraph-mcp; no se modificó código de :docugraph-core ni :docugraph-mcp en este experimento).
• Comando de compilación previo (ya existente de EXP-02, no repetido): ./gradlew :docugraph-mcp:installDist (binario reutilizado sin cambios).

Limitaciones

• Una sola tarea real: este experimento valida el umbral con BE-04 únicamente; no cubre docs/frontend/FE-0X ni cadenas aún más profundas o con más bifurcaciones. Se recomienda repetir con al menos una tarea de docs/frontend/ antes de fijar el umbral como definitivo para MVP.
• Estimación de tokens por caracteres: se usó la heurística de 4 caracteres/token (igual limitación que EXP-02); la razón de reducción es robusta a esta aproximación, no los valores absolutos.
• Comparador “cadena de la tarea” es sensible al overhead de renderizado: con cadenas cortas o documentos muy concentrados (como en BE-04, donde MASTER-00 es un documento largo e ineludible en la cadena), este comparador puede volverse negativo sin que ello indique una regresión del resolver; el comparador relevante para el criterio de aceptación de RES-03 §4.4 sigue siendo “bundle vs. contexto completo”.
• Nodos fuera de workspace omitidos sin advertencia explícita en el bundle: AGENTS/README no generan ninguna nota visible en ## Inclusion report; solo se detectan comparando contra el depends_on declarado en el frontmatter fuente. Se recomienda evaluar (fuera del alcance de este experimento, ver Restricciones) si validate_traceability debería señalarlos como LINK_BROKEN_DEPENDS al auditar docs/ de forma aislada.

⚠️ Caveat pre-registrado: esta evidencia corresponde a una sola tarea real (BE-04) del catálogo de producto; no garantiza generalidad a todas las cadenas de docs/backend/ o docs/frontend/. El umbral se considera confirmado con evidencia real suficiente para continuar la Fase B, no como cierre definitivo de la pregunta de investigación H03.

Decisión

CONTINUAR — el umbral ≥40% de DEC-006 se sostiene con margen amplio (70.17%) en una tarea real del catálogo de producto, con cobertura 100%, omisión crítica 0% y precisión 100%. Registrado en DEC-LOG (DEC-007, confirmación, sin cambio de valor).

Próxima acción

1. Registrar DEC-007 en DEC-LOG confirmando el umbral con esta evidencia real.
2. Repetir la validación con al menos una tarea real de docs/frontend/ para ampliar la cobertura de evidencia antes de declarar el criterio §5.2 de MASTER-00 cumplido para MVP.
3. Evaluar H04 (calidad de implementación con vs. sin bundle) con un agente real, alineado con el Kotlin AI Benchmark (DEC-003 §3).

---

Registro de estado

Campo	Valor
Estado	COMPLETADA
Fecha de apertura	2026-08-11
Fecha de ejecución	2026-08-11
Fecha de cierre	2026-08-11
Cambio de estado en	DEC-LOG (DEC-007)