Documento Maestro de Contexto del Proyecto DocuGraph v0.01

DOCUMENTO MAESTRO DE CONTEXTO DEL PROYECTO

Para delegación controlada a IA especializada.

• Proyecto: DocuGraph
• Versión: 0.01
• Estado: Herramienta personal del driver sobre base técnica validada (Shipaton 2026 congelado por DEC-011)
• Naturaleza: Herramienta personal de documentación atómica y contexto MCP para agentes de IA; el objetivo Shipaton 2026 queda congelado
• Estrategia de producto: Fuente de verdad en Markdown + git; lectura con Obsidian + visor web; escritura de documentos por agentes vía MCP; ecosistema self-hosted gratuito (Oracle Always Free: MCP remoto SSE/HTTP + Gitea + visor web). No existe una aplicación Desktop activa; la antigua app Compose queda como catálogo histórico (DEC-013).
• Propósito: Servir como fuente de verdad para investigación, documentación, diseño e implementación asistida por IA, y como herramienta operativa del driver en sus proyectos.

---

0. REGLAS DE GOBERNANZA

0.1 Principios

1. Separar hipótesis, evidencia, decisiones y funcionalidades.
2. Separar Gate 0, PoC, MVP Shipaton y producto futuro.
3. Mantener el catálogo completo sin convertirlo automáticamente en alcance.
4. Cada decisión importante debe indicar justificación y evidencia.
5. Cada riesgo debe tener mitigación verificable.
6. Ninguna IA puede completar información faltante mediante suposiciones.
7. OpenAPI será la fuente única de contratos REST.
8. Cada concepto debe vivir en un único documento y referenciarse mediante ID.
9. No se implementará una fase sin aprobar sus gates.
10. Los resultados negativos se documentarán. No se ocultarán ni reinterpretarán.

0.2 Estados permitidos

Categoría	Estados
Hipótesis	SIN_PROBAR, EN_PRUEBA, APOYADA, REFUTADA, INCONCLUSA
Decisiones	PROPUESTA, APROBADA, RECHAZADA, REVERSADA, TBD
Funcionalidades	CATALOGO, GATE_0, POC, MVP, POST_MVP, DESCARTADA
Tareas	BACKLOG, TODO, IN_PROGRESS, BLOCKED, DONE

---

1. RESUMEN EJECUTIVO

1.1 Nombre

DocuGraph: sistema multiplataforma de trazabilidad documental que genera context bundles verificables para agentes de programación, explicando qué recursos necesita una tarea y por qué fueron incluidos. Se apoya en documentación atómica con IDs estables y en recuperación de contexto mediante Model Context Protocol.

1.2 Problema

Los agentes de programación dependen del contexto proporcionado. En proyectos con documentación distribuida, el desarrollador debe seleccionar manualmente archivos, reglas, historias, contratos y schemas.

Este proceso puede:

• incluir información irrelevante;
• omitir dependencias;
• cargar documentos completos innecesariamente;
• propagar contradicciones;
• aumentar el trabajo de revisión.

Estas afirmaciones son hipótesis del proyecto y deberán validarse con experimentos e investigación de usuarios.

1.3 Propuesta

DocuGraph representa documentos y fragmentos mediante nodos con IDs estables y relaciones explícitas.

Ejemplo:

BR-01
→ US-01
→ IX-01
→ FE-01
→ BE-02
→ API-BE-02
→ DB-USERS

Cuando un agente solicita implementar BE-02, DocuGraph recupera los recursos vinculados, crea un context bundle y explica por qué incluyó cada elemento.

1.4 Hipótesis central

Un bundle derivado de dependencias documentales puede conservar todos los recursos obligatorios y reducir el contenido irrelevante frente a cargar toda la documentación.

Esta hipótesis debe evaluarse mediante cobertura, precisión, omisiones críticas, reducción de tokens y costo de mantenimiento.

1.5 Usuario inicial

Desarrolladores individuales y equipos pequeños que:

• trabajan principalmente desde una computadora;
• mantienen documentación dentro del repositorio;
• utilizan IDE, terminal y control de versiones;
• emplean Junie, Claude Code, Cursor u otro agente;
• necesitan implementar tareas con especificaciones distribuidas.

No existe todavía un cliente piloto real.

1.6 Perfil operativo vigente (DEC-013)

DocuGraph opera como un ecosistema self-hosted, no como una aplicación multiplataforma. :docugraph-core contiene el modelo y la validación del grafo; :docugraph-mcp sirve el contexto y las escrituras estructuradas; Obsidian, Gitea y MkDocs son las superficies humanas de lectura y revisión.

La antigua estrategia KMP Mobile + Desktop de DEC-002 (research/99_DECISION_LOG.md) se conserva como contexto histórico del catálogo, pero sus módulos de aplicación ya no forman parte del repositorio activo.

---

2. PREGUNTAS DE INVESTIGACIÓN

ID	Pregunta
RQ01	¿DocuGraph recupera todos los recursos obligatorios para una tarea?
RQ02	¿Excluye recursos irrelevantes?
RQ03	¿Reduce el tamaño del contexto?
RQ04	¿Mejora la implementación producida por un agente?
RQ05	¿Cuánto trabajo requiere crear y mantener las relaciones?
RQ06	¿El beneficio supera el costo de mantenimiento documental?
RQ07	¿El Kotlin MCP SDK permite implementar el servidor requerido?
RQ08	¿Una app móvil aporta valor fuera de la presentación para Shipaton?
RQ09	¿Los desarrolladores comprenden y confían en los bundles generados?
RQ10	¿Existe disposición real a pagar por validación, bundles o trazabilidad?
RQ11	¿El núcleo KMP puede reutilizarse entre Mobile y Desktop sin comprometer las capacidades necesarias de Desktop?
RQ12	¿La cuenta y el entitlement permiten conservar correctamente el acceso Pro entre plataformas?

---

3. HIPÓTESIS

ID	Hipótesis	Criterio inicial	Estado
H01	El bundle incluye todos los recursos obligatorios	Cobertura obligatoria del 100%	SIN_PROBAR
H02	El bundle excluye contenido irrelevante	Precisión superior al contexto monolítico	SIN_PROBAR
H03	El bundle reduce el contexto	Reducción positiva y medible	SIN_PROBAR
H04	El agente produce mejores resultados	Menos incumplimientos respecto de la spec	SIN_PROBAR
H05	Mantener el grafo requiere un esfuerzo aceptable	Se define después de medir línea base	SIN_PROBAR
H06	El servidor MCP es reproducible	Ejecución en un segundo entorno	SIN_PROBAR
H07	La visualización mejora la comprensión	Validación cualitativa con usuarios	SIN_PROBAR
H08	La app móvil aporta valor práctico	Evidencia repetida en entrevistas/pruebas	SIN_PROBAR
H09	Los usuarios pagarían por Pro	Evidencia conductual, no solo opinión	SIN_PROBAR
H10	El núcleo KMP puede reutilizarse entre Mobile y Desktop sin comprometer las capacidades necesarias de Desktop	Reutilización verificada sin pérdida de capacidades Desktop	SIN_PROBAR
H11	Los usuarios comprenden que Mobile y Desktop son superficies complementarias	Validación cualitativa con usuarios	SIN_PROBAR
H12	El acceso Desktop aumenta el valor percibido de DocuGraph Pro	Evidencia conductual o de entrevistas	SIN_PROBAR
H13	Existe una acción de supervisión o revisión que aporta valor real desde Mobile	Evidencia repetida en entrevistas/pruebas	SIN_PROBAR
H14	La cuenta y el entitlement permiten conservar correctamente el acceso Pro entre plataformas	Verificación cruzada Mobile/Desktop	SIN_PROBAR

---

4. MÉTRICAS DE EVALUACIÓN

4.1 Precisión

Recursos relevantes incluidos / Total de recursos incluidos

4.2 Cobertura

Recursos relevantes incluidos / Total de recursos relevantes esperados

4.3 Omisión crítica

Recursos obligatorios omitidos / Total de recursos obligatorios

4.4 Reducción de contexto

1 - (Tokens del bundle / Tokens del contexto completo)

4.5 Costo de preparación

• Tiempo para documentar la tarea.
• Tiempo para crear referencias.
• Tiempo para corregir referencias.
• Número de relaciones creadas manualmente.
• Número de decisiones humanas requeridas.

4.6 Calidad de implementación

• Criterios de aceptación cumplidos.
• Errores de contrato.
• Reglas de negocio omitidas.
• Archivos modificados fuera de alcance.
• Correcciones manuales necesarias.
• Pruebas aprobadas.

---

5. SECUENCIA DE ENTREGA

Equivalencia de fases (v0.7): Fase A = Gate 0, Fase B = PoC, Fase C = MVP Shipaton, Fase D = Desktop, Fase E = conexión entre dispositivos. La transición no es una reescritura de móvil a Desktop: el núcleo compartido se prepara desde la PoC.

5.1 Gate 0: viabilidad técnica

Objetivo

Comprobar que DocuGraph puede recuperar contexto mediante MCP sin depender de una aplicación móvil.

Alcance

• Servidor MCP en Kotlin.
• Repositorio demo.
• Document Loader.
• Metadata Parser.
• Graph Resolver.
• Resolución determinista de referencias.
• Tool get_task_context.
• Tool validate_traceability.
• Un cliente MCP real.
• Ejecución de BE-02.

Criterios de aprobación

1. El cliente se conecta correctamente.
2. BE-02 devuelve el conjunto esperado.
3. Las referencias rotas se detectan.
4. La salida explica cada inclusión.
5. La ejecución es reproducible.
6. No se requieren documentos ajenos a la tarea.

Decisión

• CONTINUAR: todos los criterios críticos se cumplen.
• AJUSTAR: existen fallos solucionables.
• REPETIR: evidencia insuficiente.
• DETENER: el enfoque no resulta viable.

Regla de código (v0.7): se permite escribir únicamente el código mínimo requerido para ejecutar y evaluar Gate 0. No se implementará la PoC, el MVP ni funcionalidades posteriores antes de aprobar Gate 0.

5.2 PoC: validación de contexto

Objetivo

Evaluar cuantitativamente la recuperación documental.

Alcance

• Tres tareas.
• Gold standard manual por tarea.
• Contexto monolítico de comparación.
• Bundles generados por DocuGraph.
• Métricas de precisión, cobertura y tokens.
• Medición del trabajo de preparación.
• Núcleo documental preparado como módulos reutilizables.
• Repositorios de datos abstractos.
• Resultados consumibles por diferentes clientes.

Criterios mínimos

1. Cobertura obligatoria: 100%.
2. Omisión crítica: 0%.
3. Reducción de contexto: positiva.
4. Inclusiones justificadas.
5. Ningún bundle incompleto se marca como válido.

La reducción mínima aceptable se decidirá después de obtener la línea base.

Comparadores (cuando sea viable):

1. Contexto documental completo.
2. Selección manual.
3. Bundle generado por DocuGraph.
4. Recuperación alternativa simple — solo si se aprueba mediante decisión; no se incorpora automáticamente al alcance.

Validez de la evidencia: la PoC proporciona evidencia inicial dentro del repositorio demo. No demuestra que los resultados se generalicen a otros proyectos, equipos o estructuras documentales.

5.3 Gate de integración de la aplicación

Debe resolverse después de Gate 0 y antes de implementar el MVP móvil.

Plan A: ejecución en tiempo real

La app consume resultados reales del servidor MCP.

Plan B: demostración verificable

La app muestra bundles generados previamente por la PoC.

Condiciones:

• deberán identificarse como resultados precalculados;
• no se presentarán como ejecución en vivo;
• el video mostrará evidencia separada del servidor MCP funcional.

5.4 MVP Shipaton

Objetivo

Comunicar y monetizar la capacidad validada mediante una aplicación publicable.

Pantallas principales (máximo contractual: 12)

Las pantallas se organizan alrededor de cinco flujos; splash, bienvenida, configuración y resultado de compra son auxiliares, no el centro de la demostración.

ID	Pantalla	Flujo
S01	Splash	Auxiliar
S02	Bienvenida	Auxiliar
S03	Proyecto demo	F1 — Explorar el proyecto demo
S04	Detalle del proyecto	F1
S05	Lista de tareas	F2 — Seleccionar una tarea
S06	Dependencias	F4 — Inspeccionar trazabilidad, métricas y errores
S07	Context bundle y métricas	F3 — Consultar el bundle
S08	Estado o ejecución MCP	F3
S09	Validación	F4
S10	Paywall	F5 — Comprar Pro y acceder a Desktop
S11	Resultado de compra (+ acceso a Desktop)	F5
S12	Configuración	Auxiliar

Adiciones v0.7

• Cuenta identificada — mecanismo TBD (mínimo viable: RevenueCat App User ID; la autenticación completa permanece POST_MVP).
• Pantalla/mensaje que comunique que el acceso Pro incluye Desktop (integrado en S10/S11).
• Flujo honesto que distinga resultados en vivo y precalculados (ver §5.3).

Momento principal del producto: la tarea requería determinados recursos; DocuGraph recuperó los obligatorios, excluyó contenido innecesario y explicó cada inclusión.

RevenueCat obligatorio

• SDK.
• Offering Pro.
• Entitlement.
• Paywall.
• Compra.
• Restauración.
• Resultado.

El precio definitivo no bloquea Gate 0 ni la PoC. La integración mínima sí es un requisito de salida del MVP Shipaton.

5.5 Fase D: Desktop

Objetivo

Incorporar DocuGraph Desktop como nuevo target sobre el núcleo compartido, sin reescribir el producto móvil.

Alcance

• Nuevo target Desktop sobre el núcleo compartido.
• Conexión con repositorios locales.
• Ejecución MCP.
• Edición y reparación de referencias.
• Generación real de bundles.
• Inicio de sesión y comprobación del acceso Pro.

Estado tras DEC-013 (2026-08-14): la Desktop se reorienta a vista/lectura read-only del grafo y los documentos. Los incrementos 1–4 implementados (apertura de workspaces, listado, bundles, validación, grafo, creación/edición) quedan como editor histórico/fallback. La escritura de documentos pasa a los agentes vía MCP (:docugraph-mcp) y la lectura a Obsidian + visor web (ecosistema self-hosted gratuito en Oracle Always Free; ver DEC-013 y ROADMAP-00 Nivel 4).

Desktop no forma parte del alcance del MVP Shipaton.

5.6 Fase E: conexión entre dispositivos (sujeto a validación)

Solo se implementará si existe evidencia de valor.

Opciones sujetas a validación:

• sincronización remota;
• emparejamiento;
• conexión local;
• notificaciones;
• aprobación remota.

No se asumirán cloud, pairing ni sincronización como funcionalidades aprobadas.

5.7 Producto objetivo

Conserva el mapa completo de experiencia:

editor documental; edición de secciones; creación desde plantillas; reference picker; grafo interactivo; análisis de impacto; personalización de bundles; diff; conflictos; repositorios reales; pairing; handoff; reparación guiada; historial; colaboración.

Las 34 pantallas previamente identificadas pertenecen a esta fase y están sujetas a validación.

---

6. CATÁLOGO FUNCIONAL

6.1 Núcleo documental

ID	Función	Fase
DOC01	Metadata con IDs y referencias	Gate 0
DOC02	Repositorio demo	Gate 0
DOC03	Grafo documental	PoC
DOC04	Project Manifest	Producto
DOC05	Plantillas documentales	Producto
DOC06	Context Rules	Producto
DOC07	Historial y versiones	Producto

6.2 MCP

ID	Función	Fase
MCP01	Servidor MCP Kotlin	Gate 0
MCP02	Resources documentales	Gate 0
MCP03	get_task_context	Gate 0
MCP04	validate_traceability	Gate 0
MCP05	Resolver subgrafo	PoC
MCP06	Extraer operationId	PoC
MCP07	Prompt implement_task	PoC
MCP08	Prompt review_task_diff	Producto
MCP09	Personalizar bundle	Producto
MCP10	Handoff al agente	Producto

Resolución del grafo (v0.7): Gate 0 = resolución determinista mínima de referencias (MCP03/MCP04). PoC = resolución configurable de subgrafos, tipos de relaciones, profundidad y reglas de inclusión (MCP05).

6.3 Evaluación

ID	Función	Fase
EVAL01	Gold standard	PoC
EVAL02	Precisión	PoC
EVAL03	Cobertura	PoC
EVAL04	Tokens	PoC
EVAL05	Tiempo de mantenimiento	PoC
EVAL06	Comparación de implementación	PoC ampliada
EVAL07	Informe de resultados	MVP

6.4 Visualización

ID	Función	Fase
VIS01	Lista de dependencias	MVP
VIS02	Camino de trazabilidad	MVP
VIS03	Grafo básico	MVP opcional
VIS04	Canvas infinito	Producto
VIS05	Filtros	Producto
VIS06	Impacto	Producto
VIS07	Huérfanos	Producto

6.5 Edición

ID	Función	Fase
EDIT01	Editor Markdown	Producto
EDIT02	Editor de sección	Producto
EDIT03	Metadata	Producto
EDIT04	Reference Picker	Producto
EDIT05	Crear desde plantilla	Producto
EDIT06	Revisión diff	Producto
EDIT07	Conflictos	Producto
EDIT08	Renombrado seguro	Producto

6.6 Monetización

ID	Función	Fase
PAY01	SDK RevenueCat	MVP
PAY02	Offering	MVP
PAY03	Entitlement	MVP
PAY04	Paywall	MVP
PAY05	Purchase	MVP
PAY06	Restore	MVP
PAY07	Límites avanzados	Producto
PAY08	Acceso Desktop incluido en Pro (comunicación)	MVP

6.7 Plataforma Desktop (Fase D)

El incremento 1 cubre parcialmente DESK01, DESK02, DESK04 y DESK05 mediante el target Desktop y el gateway de workspace; DESK03, DESK06, DESK07 y DESK08 siguen pendientes.

ID	Función	Fase
DESK01	Abrir repositorios locales	Producto (Fase D)
DESK02	Cargar y analizar documentación	Producto (Fase D)
DESK03	Editar metadata y referencias	Producto (Fase D)
DESK04	Generar context bundles reales	Producto (Fase D)
DESK05	Ejecutar validaciones	Producto (Fase D)
DESK06	Visualizar el grafo completo	Producto (Fase D)
DESK07	Iniciar y administrar el servidor MCP	Producto (Fase D)
DESK08	Integración con herramientas externas	Producto (Fase D)

6.8 Conexión entre dispositivos (Fase E, sujeto a validación)

ID	Función	Fase
CONN01	Sincronización remota	Producto (Fase E, sujeto a validación)
CONN02	Emparejamiento	Producto (Fase E, sujeto a validación)
CONN03	Conexión local	Producto (Fase E, sujeto a validación)
CONN04	Notificaciones	Producto (Fase E, sujeto a validación)
CONN05	Aprobación remota	Producto (Fase E, sujeto a validación)

---

7. STACK TECNOLÓGICO

Capa	Tecnología	Estado
MCP	Kotlin MCP SDK (0.15.0)	Decidido para Gate 0
Aplicación	Kotlin Multiplatform	Decidido para MVP
UI	Compose Multiplatform	Decidido para MVP
Transporte inicial	STDIO	Implementado (Gate 0 aprobado)
Transporte remoto	Streamable HTTP / SSE	En trabajo para Oracle (DEC-013)
Documentos	Markdown + YAML frontmatter	Fuente de verdad (DEC-013)
Serialización	Kotlinx Serialization	Propuesto
Networking	Ktor	Si se requiere
Contratos	OpenAPI	Fuente única
Monetización	RevenueCat	Eliminada del código (DEC-012)
CI/CD	Gradle + GitHub Actions	Propuesto
Cloud	Oracle Always Free (2 OCPU, 12 GB) — MCP remoto + Gitea + visor web	Decidido (DEC-013), gratuito
Desktop	Compose Desktop (JVM)	Vista read-only/fallback (DEC-013)
Lectura local	Obsidian (markdown nativo, grafo, Mermaid)	Decidido (DEC-013), gratuito
Git remote propio	Gitea	Decidido (DEC-013)
Identidad / cuenta	TBD	TBD
Correo transaccional	TBD	TBD
Distribución y actualización Desktop	TBD	TBD

---

8. ARQUITECTURA

8.1 Gate 0

Cliente MCP
    │
    ▼
DocuGraph MCP Server
    ├── Document Loader
    ├── Metadata Parser
    ├── Graph Resolver
    ├── Bundle Builder
    ├── Validator
    └── Evaluation Collector
    │
    ▼
Repositorio demo

8.2 MVP Shipaton

App Android/iOS
    ├── Proyecto demo
    ├── Tareas
    ├── Dependencias
    ├── Bundle y métricas
    ├── Validación
    └── RevenueCat

8.3 Producto futuro

App móvil, tablet o desktop
    │
    ▼
DocuGraph Companion
    │
    ▼
Repositorio autorizado
    │
    ▼
Cliente MCP / agente

8.5 Arquitectura self-hosted (DEC-013, vigente)

Agentes (Claude Code / Codex / Antigravity)
    │   escriben documentos vía MCP
    ▼
┌─────────────────────────────────────────────────┐
│ ORACLE ALWAYS FREE (2 OCPU, 12 GB)              │
│  • :docugraph-mcp (SSE/HTTP) → grafo,           │
│     validación DAG, bundles, upsert/update      │
│  • Gitea → remote git propio (fuente de verdad) │
│  • Visor web → render .md + grafo (navegador)   │
└─────────────────────────────────────────────────┘
    ▲
    │  git push / pull + lectura local
┌─────────────────────────────────────────────────┐
│ LOCAL                                            │
│  • Obsidian → vault sobre el clon (lectura/edición│
│     markdown nativo, grafo, Mermaid)             │
│  • app Desktop → vista read-only / fallback      │
└─────────────────────────────────────────────────┘

8.4 Arquitectura objetivo KMP (PROPUESTA)

Estado: PROPUESTA — sujeto a validación técnica (H10). No asume que todo el código o toda la UI serán compartidos; las capacidades dependientes del SO permanecen en módulos específicos.

DocuGraph
├── shared-domain
│   ├── modelos
│   ├── metadata
│   ├── relaciones
│   └── contratos
│
├── shared-engine
│   ├── Document Loader abstractions
│   ├── Metadata Parser
│   ├── Graph Resolver
│   ├── Bundle Builder
│   ├── Validator
│   └── Evaluation Collector
│
├── shared-data
│   ├── ProjectRepository
│   ├── DemoProjectRepository
│   ├── PrecomputedProjectRepository
│   └── contratos para implementaciones locales o remotas
│
├── shared-ui
│   ├── proyectos
│   ├── tareas
│   ├── dependencias
│   ├── bundles
│   ├── métricas
│   ├── validación
│   └── estado Pro
│
├── androidApp
├── iosApp
├── desktopApp
│   ├── sistema de archivos
│   ├── procesos locales
│   ├── repositorio local
│   ├── servidor MCP
│   └── integración externa
│
└── mcp-server

Mapeo orientativo desde la nomenclatura previa del monorepo: :docugraph-core → shared-domain + shared-engine; :docugraph-app → shared-ui + apps de plataforma; :docugraph-mcp → mcp-server; :docugraph-backend → sin equivalente inicial (cloud no requerido; Fase E sujeta a validación).

---

9. INVESTIGACIÓN Y EXPERIMENTOS

9.1 Estructura de archivos

research/
├── 00_RESEARCH_PLAN.md
├── 01_RESEARCH_QUESTIONS.md
├── 02_HYPOTHESES.md
├── 03_METRICS.md
├── experiments/
├── sessions/
├── evidence/
├── findings/
└── 99_DECISION_LOG.md

9.2 Plantilla de experimento

# EXP-XX: Título

## Hipótesis relacionadas
HXX.

## Pregunta
¿Qué queremos averiguar?

## Método
Cómo se ejecutará la prueba.

## Preparación
Datos, fixtures y gold standard.

## Métricas
Qué se medirá.

## Criterio definido antes de ejecutar
Qué resultado apoya o refuta la hipótesis.

## Resultados
Datos obtenidos.

## Evidencia
Logs, archivos, capturas y outputs.

## Limitaciones
Qué no permite concluir este experimento.

## Decisión
CONTINUAR / AJUSTAR / REPETIR / DETENER.

## Próxima acción
Una acción concreta.

9.3 Primer experimento obligatorio

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

Debe medir:

• cobertura;
• precisión;
• omisiones;
• tokens;
• recursos incluidos;
• recursos excluidos;
• tiempo para preparar metadata;
• errores manuales.

---

10. REGISTRO DE DECISIONES

Cada decisión utilizará este formato:

# DEC-XXX: Título

- Fecha:
- Estado:
- Hipótesis relacionadas:
- Experimentos consultados:
- Evidencia:
- Decisión:
- Justificación:
- Alternativas rechazadas:
- Consecuencias:
- Aspectos aún inciertos:
- Fecha de revisión:

Ninguna decisión importante se basará únicamente en opiniones.

---

11. RIESGOS

Riesgo	Probabilidad	Impacto	Mitigación
El bundle no mejora el contexto	Media	Crítico	PoC cuantitativa
El gold standard es incorrecto	Media	Alto	Revisión manual y casos simples
MCP SDK no cubre el flujo	Media	Alto	Gate 0 temprano
La metadata exige demasiado trabajo	Alta	Alto	Medir costo de preparación
Mobile-first no aporta valor	Alta	Alto	Tratar móvil como packaging
Pairing es demasiado complejo	Alta	Alto	Posponer y evaluar desktop
El MVP vuelve a crecer	Alta	Alto	Límite contractual de 12 pantallas
RevenueCat consume demasiado tiempo	Media	Medio	Integración mínima
La demo exagera capacidades	Baja	Alto	Transparencia entre live y precalculado
No existe demanda real	Alta	Crítico	Investigación con usuarios
Exceso de abstracción multiplataforma	Media	Alto	Compartir solo lo demostrado reutilizable en PoC; medir % de código compartido vs. específico
UI compartida poco adecuada para Desktop	Media	Alto	Compartir ViewModels/estado, no pantallas completas; revisión de usabilidad en Fase D
Dependencia innecesaria de servicios cloud	Media	Alto	Regla contractual: Fase E solo con evidencia; ningún cloud sin decisión
Complejidad de identidad entre plataformas	Media	Alto	Identidad mínima vía RevenueCat App User ID; mecanismo definitivo TBD
Compra móvil sin suficiente valor Desktop	Media	Alto	Validar H12/H13 con usuarios; comunicación honesta de Desktop en el MVP
Dificultad para distribuir y actualizar Desktop	Media	Medio	Estrategia de distribución TBD; evaluar opciones de empaquetado JVM en Fase D
Divergencia funcional entre Mobile y Desktop	Media	Alto	Núcleo compartido (H10) y matriz de capacidades por plataforma
Alcance excesivo al lanzar todas las plataformas a la vez	Alta	Alto	Secuencia contractual A→E; MVP solo móvil; Desktop en Fase D

---

12. CRITERIOS DE ÉXITO

Gate 0

• Cliente MCP conectado.
• Dos tools funcionales.
• Ejecución reproducible.
• Referencias rotas detectadas.
• Inclusiones explicadas.

PoC

• Tres tareas evaluadas.
• Cobertura obligatoria de 100%.
• Omisión crítica de 0%.
• Reducción positiva.
• Precisión medible.
• Costo de mantenimiento documentado.

MVP

• App publicable.
• Flujo completo sin callejones.
• RevenueCat funcional.
• Demo honesta.
• Video inferior a dos minutos.
• Resultados y limitaciones visibles.
• Cinco flujos organizados (F1–F5) con pantallas auxiliares diferenciadas.
• Comunicación de que Pro incluye Desktop.
• Cuenta identificada (mecanismo TBD).

---

13. DOCUMENTACIÓN DERIVADA

La IA documentadora deberá generar, en este orden:

1. GATE_0_SPEC.md
2. RESEARCH_PLAN.md
3. 02_HYPOTHESES.md
4. 03_METRICS.md
5. domain/METADATA_SPEC.md
6. mcp/MCP_GATE0_SPEC.md
7. experiments/EXP-01_recuperacion_contexto.md
8. POC_SRS.md
9. POC_TEST_PLAN.md
10. MVP_SCOPE.md
11. MVP_SRS.md
12. MVP_INTERACTION_SPECS/
13. REVENUECAT_PLAN.md
14. STORE_RELEASE_PLAN.md
15. PRODUCT_BACKLOG.md
16. DECISION_LOG.md

Estado de generación de los derivados: ver RES-00 (research/00_RESEARCH_PLAN.md).

---

14. CONTRATO PARA LA IA DELEGADA

La IA deberá:

• distinguir hechos, hipótesis, decisiones y sugerencias;
• conservar los IDs definidos;
• no inventar clientes, métricas ni resultados;
• no marcar hipótesis como validadas sin evidencia;
• no ampliar el alcance sin registrar una decisión;
• no asumir pairing, cloud o IA externa;
• no duplicar contratos OpenAPI;
• indicar claramente los campos TBD;
• mantener Gate 0, PoC, MVP y producto como niveles separados;
• solicitar evidencia cuando una conclusión dependa de resultados no disponibles;
• señalar contradicciones antes de generar documentos derivados.

La IA no deberá:

• implementar la PoC, el MVP ni funcionalidades posteriores antes de aprobar Gate 0 (se permite únicamente el código mínimo requerido para ejecutar y evaluar Gate 0);
• diseñar las 34 pantallas como alcance del MVP;
• convertir Desktop completo en alcance del MVP Shipaton;
• asumir que todo el código o toda la UI serán compartidos;
• prometer sincronización remota, pairing ni cloud;
• presentar resultados precalculados como ejecución en vivo;
• proponer funciones nuevas como si estuvieran aprobadas;
• modificar métricas después de conocer el resultado sin registrar el cambio;
• eliminar resultados negativos;
• usar opiniones como sustituto de evidencia.

---

15. CRITERIO DE AVANCE

¿Existe una hipótesis explícita?
        ↓
¿Hay un experimento adecuado?
        ↓
¿El criterio fue definido antes de ejecutar?
        ↓
¿Existe evidencia guardada?
        ↓
¿El resultado es reproducible?
        ↓
CONTINUAR / AJUSTAR / REPETIR / DETENER

---

DECISIÓN OFICIAL

DocuGraph se tratará inicialmente como una investigación de producto y una validación técnica. La prioridad no es construir todas las funciones imaginadas, sino demostrar que el contexto recuperado mediante dependencias documentales conserva la información obligatoria, reduce contenido irrelevante y justifica el esfuerzo necesario para mantener el grafo.

Actualización v0.8 (DEC-011, 2026-08-13): la validación técnica quedó demostrada (Gate 0 aprobado, PoC con reducción 63–70%). El objetivo Shipaton 2026 se congela y DocuGraph pasa a ser la herramienta personal del driver para gestionar sus proyectos (creación → uso → seguimiento de tareas), avanzando de las bases a lo avanzado según el roadmap ROADMAP-00. Nada de la documentación previa se elimina; el roadmap solo reorienta prioridades. El trabajo inmediato es el Nivel 1 del roadmap: tool de escritura MCP, flujo diario con agentes y convención de tareas. La metodología de documentación que el driver aplica a sus proyectos (problema/requisitos, roles y casos de uso, flujos, diseño/mockups, arquitectura/BD, historias de usuario y tareas) queda documentada en METODOLOGIA-00.

Actualización v0.9 (DEC-012, 2026-08-13): como herramienta personal, DocuGraph abandonó los targets Android/iOS, el gateway RevenueCat, las pantallas paywall y las pantallas demo del MVP móvil. La app móvil y la monetización quedan como histórico trazable (DEC-009/DEC-010), sin implementación activa.

Actualización v0.9+ (DEC-013, 2026-08-14): la arquitectura se reorienta a un ecosistema self-hosted y 100% gratuito. La fuente de verdad permanece en Markdown + git. La lectura pasa a Obsidian (markdown nativo, grafo, Mermaid) + un visor web; la escritura de documentos la realizan los agentes vía MCP (:docugraph-mcp, que valida el DAG antes de escribir). Una instancia Oracle Cloud Always Free (2 OCPU, 12 GB) aloja el MCP remoto (SSE/HTTP), Gitea (remote git propio) y el visor web. La aplicación Desktop se retira del repositorio y queda solo como histórico documental. Véase DEC-013 (research/99_DECISION_LOG.md) y ROADMAP-00 Nivel 4.

Actualización operativa v0.01 (2026-08-14): la implementación del ecosistema está preparada en deploy/oracle/: Compose separa los datos de Gitea del checkout /workspace, Caddy protege /mcp y /sse con X-MCP-API-KEY, y MkDocs + GraphExportMain publican el visor desde DocGraphWorkspace. El flujo documentado es pull → escritura MCP → validate_traceability → revisión → commit/push; los secretos permanecen en .env local. La activación y los smoke tests contra la nueva pila Oracle aún deben ejecutarse en el host remoto.

Alcance vigente:

• Gate 0 (Fase A): servidor MCP y dos tools; resolución determinista de referencias.
• PoC (Fase B): tres tareas, evaluación cuantitativa y núcleo documental reutilizable.
• MVP Shipaton (Fase C): congelado (DEC-011); la app demo S01–S12 y el gateway RevenueCat quedan como referencia, sin publicación en tiendas.
• Cliente propio (Fase D): retirado del código; Obsidian, Gitea y el visor web cubren la lectura y revisión sin mantener una aplicación Desktop.
• Ecosistema self-hosted (Nivel 4): MCP remoto SSE/HTTP + Gitea + visor web en Oracle Always Free; lectura local con Obsidian (DEC-013).
• Conexión entre dispositivos (Fase E): sujeto a evidencia de valor.
• Producto completo: sujeto a resultados y validación con usuarios.

Posicionamiento (v0.9+, DEC-013): DocuGraph es la herramienta personal del driver basada en Markdown + git como fuente de verdad: los agentes (Claude Code/Codex/Antigravity) escriben los documentos atómicos vía MCP, el driver los lee y navega en Obsidian, Gitea y el visor web, y una instancia Oracle Always Free aloja el MCP remoto, Gitea y el visor, todo gratis y self-hosted. Las aplicaciones Mobile/Desktop y los pagos quedan como histórico de alcance del Shipaton, fuera del foco actual.

Fin del documento maestro.

---

Índice de trazabilidad

• Dependientes directos (frontmatter depends_on: [MASTER-00]):
  • AGENTS.md (AGENTS) — Protocolo de agentes de IA.
  • VISION-00 (VISION-00) — Visión de negocio (propuesta).
  • MANIFEST-01 (MANIFEST-01) — Manifiesto y matriz de trazabilidad.
  • RES-00 (research/00_RESEARCH_PLAN.md) — Plan de investigación.
  • RES-01 (research/01_RESEARCH_QUESTIONS.md) — Preguntas de investigación.
  • RES-02 (research/02_HYPOTHESES.md) — Hipótesis.
  • RES-03 (research/03_METRICS.md) — Métricas.
  • EXP-01 (research/experiments/EXP-01_recuperacion_contexto.md) — Primer experimento.
  • DEC-LOG (research/99_DECISION_LOG.md) — Registro de decisiones.
• Relacionados:
  • README.md (README) — Arquitectura del monorepo.