Saltar a contenido

Plan de Acción: Alineación con Estándares y Evolución de DocuGraph MCP

Este documento operacionaliza las conclusiones y recomendaciones del hallazgo FIND-02, organizando las mejoras en paquetes de trabajo e ítems de acción atómicos (ACT-01 a ACT-11).

Cada ítem cuenta con objetivo técnico, módulo afectado, criterios de aceptación verificables y estado de ejecución para que el driver y los agentes puedan abordarlos y resolverlos de forma secuencial y trazable.

1. Cuadro Resumen de Ítems de Acción

graph TD
    subgraph P1_Inmediata [Fase 1: Protocolo MCP y Fricción Zero (P1)]
        A1[ACT-01: MCP Resources Nativos]
        A2[ACT-02: MCP Prompts Nativos]
        A3[ACT-03: infer_dependencies]
        A4[ACT-04: scaffold_document]
    end
    subgraph P2_Estandares [Fase 2: Estándares y Rendimiento (P2)]
        A5[ACT-05: Plantilla MADR / ADR-XX]
        A6[ACT-06: Taxonomía Diátaxis]
        A7[ACT-07: Diagramas C4 Editoriales]
        A11[ACT-11: Visor Visual diagram-design]
        A8[ACT-08: GraalVM Native Image]
    end
    subgraph P3_Avanzado [Fase 3: Código Vivo y Búsqueda Híbrida (P3)]
        A9[ACT-09: verify_code_traceability]
        A10[ACT-10: search_knowledge DAG+BM25]
    end
    P1_Inmediata --> P2_Estandares
    P2_Estandares --> P3_Avanzado
ID Título Módulo Principal Prioridad Estado
ACT-01 Exposición de MCP Resources (docugraph://) :docugraph-mcp P1 (Inmediata) COMPLETADO
ACT-02 Registro de MCP Prompts Nativos :docugraph-mcp P1 (Inmediata) COMPLETADO
ACT-03 Inferencia Automática de Dependencias (infer_dependencies) :docugraph-core / :docugraph-mcp P1 (Inmediata) PENDIENTE
ACT-04 Generación Asistida de Documentos (scaffold_document) :docugraph-core / :docugraph-mcp P1 (Inmediata) PENDIENTE
ACT-05 Formalización de Plantilla MADR para ADRs (ADR-XX) docs/templates/ / :docugraph-core P2 (Alta) PENDIENTE
ACT-06 Clasificación Diátaxis en Frontmatter y Filtrado docs/ / :docugraph-core P2 (Alta) PENDIENTE
ACT-07 Estandarización de Arquitectura con Diagramas C4 Editoriales docs/03_ARCHITECTURE.md P2 (Alta) PARCIAL (base en ACT-11)
ACT-08 Distribución CLI Nativa con GraalVM Native Image docugraph-mcp/build.gradle.kts P2 (Alta) PENDIENTE
ACT-09 Verificación de Trazabilidad Documentación-Código (AST) :docugraph-core / :docugraph-mcp P3 (Media) PENDIENTE
ACT-10 Recuperación Híbrida de Contexto (DAG + BM25) :docugraph-core / :docugraph-mcp P3 (Media) PENDIENTE
ACT-11 Superficie Visual Editorial con diagram-design docs/ / visor MkDocs P2 (Alta) COMPLETADO

2. Desglose Detallado de Ítems de Acción

Fase 1: Protocolo MCP y Reducción de Fricción (Prioridad 1)

ACT-01: Exposición de MCP Resources Nativos (docugraph://)

  • Problema: Los clientes MCP solo pueden interactuar mediante llamadas a herramientas (tools). No pueden navegar ni suscribirse a la estructura del workspace de forma declarativa.
  • Solución Técnica:
  • Registrar manejadores de recursos en ServerFactory.kt usando server.addResource(...):
    • docugraph://workspace/nodes $\rightarrow$ JSON con lista de metadatos de todos los nodos.
    • docugraph://workspace/graph $\rightarrow$ JSON con lista de adyacencia (nodos y aristas).
    • docugraph://workspace/node/{id} $\rightarrow$ Contenido y frontmatter del nodo solicitado.
    • docugraph://workspace/openapi $\rightarrow$ Contrato OpenAPI unificado.
    • docugraph://workspace/audit-report $\rightarrow$ Reporte estático de salud y ciclos del workspace.
  • Emitir notificaciones de actualización cuando se invoque upsert_document o upsert_batch.
  • Criterios de Aceptación:
  • listResources lista las URIs registradas.
  • readResource devuelve el contenido JSON/Markdown exacto para cada URI soportada.
  • Tests unitarios e integración en :docugraph-mcp cubren lectura de recursos.
  • Ejecución (2026-08-19): implementado en McpFeatures.kt (registerWorkspaceResources), conectado en ServerFactory.kt con capabilities resources(listChanged, subscribe). Notificación resources/updated tras upsert_document/upsert_batch. Tests en ServerFactoryIntegrationTest.kt. COMPLETADO.

ACT-02: Registro de MCP Prompts Nativos

  • Problema: Los desarrolladores deben copiar manualmente las directrices y templates de prompt (prompt_implement_task, prompt_audit_traceability).
  • Solución Técnica:
  • Registrar prompts nativos en ServerFactory.kt con server.addPrompt(...):
    • prompt_implement_task(taskId): Inyecta bundle de get_task_context y directrices modulares.
    • prompt_audit_traceability(): Inyecta el reporte de validate_traceability y guía de resolución de ciclos/huérfanos.
    • prompt_analyze_impact(taskId): Inyecta el análisis downstream y checklist de regresión.
  • Criterios de Aceptación:
  • Clientes MCP descubren los prompts mediante listPrompts.
  • getPrompt retorna los mensajes estructurados listos para ser consumidos por el LLM.
  • Tests de integración verifican la generación de mensajes con parámetros dinámicos.
  • Ejecución (2026-08-19): implementado en McpFeatures.kt (registerMcpPrompts): prompt_implement_task(taskId), prompt_audit_traceability(), prompt_analyze_impact(taskId), todos con datos vivos del workspace. Tests en ServerFactoryIntegrationTest.kt. COMPLETADO.

ACT-03: Inferencia Automática de Dependencias (infer_dependencies)

  • Problema: Escribir manualmente links.depends_on en YAML es propenso a olvidos y errores tipográficos.
  • Solución Técnica:
  • Crear en :docugraph-core el componente DependencyInferrer:
    • Escanea el cuerpo Markdown buscando enlaces relativos [US-01](path), referencias a tablas table: users, operaciones operationId: loginUser y menciones de IDs en mayúsculas (BE-XX, FE-XX, US-XX).
    • Resuelve los IDs atómicos correspondientes en el workspace.
  • Exponer la herramienta MCP infer_dependencies(path: String, content: String?) que devuelve la lista de IDs sugeridos.
  • Agregar parámetro autoLink: Boolean = false en upsert_document para inyectar automáticamente dependencias inferidas si el usuario lo solicita.
  • Criterios de Aceptación:
  • Si un documento referencia [US-01](...), infer_dependencies incluye US-01.
  • No genera ciclos recursivos hacia sí mismo.
  • Tests unitarios en :docugraph-core validan inferencia con diversos patrones Markdown.

ACT-04: Generación Asistida de Documentos (scaffold_document)

  • Problema: Crear un nuevo documento requiere copiar y pegar manualmente la estructura de frontmatter y secciones estándar.
  • Solución Técnica:
  • Implementar herramienta MCP scaffold_document(type: String, title: String, upstreamIds: List<String>?, path: String?).
  • Calcula automáticamente el siguiente identificador numérico disponible según el tipo (US-XX, BE-XX, FE-XX, ADR-XX).
  • Genera el archivo con el frontmatter pre-poblado y el esqueleto de secciones según la plantilla oficial en docs/templates/.
  • Criterios de Aceptación:
  • Invocación con type: user_story genera un US-XX correlativo con plantilla PLANTILLA_US.md.
  • El archivo generado pasa la validación estricta de validate_traceability.

Fase 2: Estándares de la Industria y Rendimiento (Prioridad 2)

ACT-05: Formalización de Plantilla MADR para Architecture Decision Records (ADR-XX)

  • Problema: El registro de decisiones actual (research/99_DECISION_LOG.md) es un único archivo plano, dificultando el enlace granular por dependencias DAG.
  • Solución Técnica:
  • Crear docs/templates/PLANTILLA_ADR.md basada en MADR (Markdown Any Decision Record).
  • Soporte para tipo type: adr en el validador de :docugraph-core.
  • Permitir enlazar ADRs atómicos individuales a componentes arquitectónicos y tareas.
  • Criterios de Aceptación:
  • Plantilla MADR versionada en docs/templates/.
  • Nodos ADR-XX reconocidos en el grafo sin errores de esquema.

ACT-06: Clasificación Diátaxis en Frontmatter y Filtrado

  • Problema: Todos los documentos se tratan con igual peso sin discriminar su propósito pedagógico o descriptivo.
  • Solución Técnica:
  • Documentar y adoptar los 4 tipos de Diátaxis (tutorial, how_to, reference, explanation) en METADATA_SPEC.md y METODOLOGIA-00.md.
  • Incorporar opción diataxisFilter: List<String>? en get_task_context y list_tasks para filtrar información superflua según el rol del agente.
  • Criterios de Aceptación:
  • Esquema YAML valida tipos Diátaxis sin advertencias.
  • get_task_context respeta filtros de clasificación cuando son especificados.

ACT-07: Estandarización de Diagramas de Arquitectura con C4 Editorial

  • Problema: Los diagramas arquitectónicos actuales usan notaciones heterogéneas (ASCII) y no se integran con el skill visual editorial.
  • Solución Técnica:
  • Actualizar docs/03_ARCHITECTURE.md y specs de interacción usando bloques Mermaid con sintaxis C4 (C4Context, C4Container, C4Component) y/o diagramas editoriales HTML+SVG generados con el skill diagram-design (ver ACT-11).
  • Validar renderizado en el visor estático MkDocs Material y en Obsidian.
  • Criterios de Aceptación:
  • Diagramas L1 (Contexto), L2 (Contenedores) y L3 (Componentes) renderizan correctamente en MkDocs.
  • Cada componente C4 cita su nodo atómico correspondiente.
  • Los diagramas generados por diagram-design son archivos autocontenidos (HTML/SVG) sin dependencias externas.

ACT-08: Distribución CLI Nativa con GraalVM Native Image

  • Problema: El arranque JVM local (1–2s) genera latencia perceptible al ser invocado repetidamente por herramientas CLI o IDEs en modo STDIO.
  • Solución Técnica:
  • Configurar plugin org.graalvm.buildtools.native en docugraph-mcp/build.gradle.kts.
  • Configurar reflection metadata y recursos para Ktor/MCP SDK.
  • Producir ejecutable nativo (docugraph-mcp.exe en Windows / binario ELF en Linux/macOS).
  • Criterios de Aceptación:
  • Binario nativo compila exitosamente.
  • Tiempo de inicio en STDIO < 15 ms.
  • Consumo de memoria RAM < 35 MB.

ACT-11: Superficie Visual Editorial con diagram-design

  • Problema: La documentación atómica es textual y los diagramas Mermaid no se ven en todas las superficies; el usuario no tiene una vista editorial de la arquitectura, flujos y trazabilidad.
  • Solución Técnica:
  • Integrar el skill editorial diagram-design (Claude Code/Codex/Pi, MIT) como recurso para agentes del monorepo.
  • Generar diagramas editoriales HTML+SVG autocontenidos (28 tipos: arquitectura, flujo, secuencia, ER, timeline, swimlane, C4, árboles, etc.) para los documentos clave:
    • docs/03_ARCHITECTURE.md (ARCH-03) — arquitectura L1/L2/L3.
    • Flujos IX-01 a IX-04 y la cadena MCP US-04/US-05.
    • Matrices y grafos de trazabilidad del workspace.
  • Exponer los diagramas generados en el visor MkDocs Material (como archivos estáticos enlazados/incrustados) y en Obsidian (vista previa directa de HTML/SVG), de modo que el propio usuario y cualquier usuario con acceso puedan ver la documentación sin la app KMP (congelada en DEC-011).
  • Criterios de Aceptación:
  • Al menos 3 diagramas editoriales autocontenidos renderizan correctamente en MkDocs y Obsidian.
  • Cada diagrama enlaza o cita su nodo atómico (ARCH-03, IX-XX, US-XX) correspondiente.
  • Los diagramas se generan desde fuentes versionadas en docs/ (Markdown/Mermaid) sin estado de sesión.
  • Ejecución (2026-08-19): creados 3 diagramas editoriales autocontenidos en docs/diagrams/: architecture.html (L1/L2/L3), mcp-context-flow.html (US-04/US-05) y traceability-dag.html (cadenas DAG). Enlazados desde docs/03_ARCHITECTURE.md §0. Estilo editorial diagram-design (HTML+SVG autocontenido, sin dependencias externas). COMPLETADO.

Fase 3: Puente con Código Vivo y Búsqueda Avanzada (Prioridad 3)

ACT-09: Verificación de Trazabilidad Documentación-Código (AST)

  • Problema: Desconexión entre especificaciones y código fuente (Doc-to-Code Drift).
  • Solución Técnica:
  • Implementar herramienta verify_code_traceability(projectSlug: String?) en :docugraph-core.
  • Escanea archivos .kt, .ts, .java buscando correspondencias con operationId de OpenAPI y tablas de base de datos.
  • Identifica funciones o endpoints sin documentar y especificaciones no implementadas en código.
  • Criterios de Aceptación:
  • Reporte identifica rutas y métodos huérfanos.
  • Salida estructurada exportable a formato SARIF para CI/CD.

ACT-10: Recuperación Híbrida de Contexto (Grafo DAG + BM25)

  • Problema: El agente solo puede recuperar contexto si conoce el taskId exacto; no puede realizar búsquedas libres en lenguaje natural preservando dependencias obligatorias.
  • Solución Técnica:
  • Implementar herramienta search_knowledge(query: String, filterType: String?, maxHops: Int = 2).
  • Ejecuta búsqueda léxica/BM25 local sobre el corpus Markdown y expande los mejores resultados a través del grafo topológico.
  • Criterios de Aceptación:
  • Búsqueda por lenguaje natural ("cómo funciona la autenticación") retorna los nodos relevantes y sus dependencias upstream obligatorias en un solo bundle coherente.

3. Protocolo de Ejecución Paso a Paso

Para abordar estos ítems de forma ordenada: 1. Seleccionar el ítem objetivo siguiendo la prioridad (P1 $\rightarrow$ P2 $\rightarrow$ P3). 2. Ejecutar en rama dedicada de GitFlow (feature/act-XX-[slug]). 3. Implementar cambios en :docugraph-core o :docugraph-mcp con tests unitarios y de integración asociados. 4. Verificar que ./gradlew test pase con 100% de éxito. 5. Actualizar el estado del ítem en este documento (PENDIENTE $\rightarrow$ COMPLETADO). 6. Integrar en develop mediante Squash Merge.

4. Referencias y Trazabilidad