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

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:
  1. listResources lista las URIs registradas.
  2. readResource devuelve el contenido JSON/Markdown exacto para cada URI soportada.
  3. 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:
  1. Clientes MCP descubren los prompts mediante listPrompts.
  2. getPrompt retorna los mensajes estructurados listos para ser consumidos por el LLM.
  3. 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:
  1. Si un documento referencia [US-01](...), infer_dependencies incluye US-01.
  2. No genera ciclos recursivos hacia sí mismo.
  3. 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:
  1. Invocación con type: user_story genera un US-XX correlativo con plantilla PLANTILLA_US.md.
  2. 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:
  1. Plantilla MADR versionada en docs/templates/.
  2. 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:
  1. Esquema YAML valida tipos Diátaxis sin advertencias.
  2. 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:
  1. Diagramas L1 (Contexto), L2 (Contenedores) y L3 (Componentes) renderizan correctamente en MkDocs.
  2. Cada componente C4 cita su nodo atómico correspondiente.
  3. 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:
  1. Binario nativo compila exitosamente.
  2. Tiempo de inicio en STDIO < 15 ms.
  3. 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:
  1. Al menos 3 diagramas editoriales autocontenidos renderizan correctamente en MkDocs y Obsidian.
  2. Cada diagrama enlaza o cita su nodo atómico (ARCH-03, IX-XX, US-XX) correspondiente.
  3. 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:
  1. Reporte identifica rutas y métodos huérfanos.
  2. 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:
  1. 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

• FIND-02: Evaluación de Estándares y FODA
• ROADMAP-00: Roadmap DocuGraph
• METODOLOGIA-00: Metodología del Driver
• MCP-SPEC: Especificación del Servidor MCP
• MASTER-00: Master Context y Gobernanza