Registro de Decisiones DocuGraph

Registro de Decisiones

Ninguna decisión importante se basará únicamente en opiniones (§10 de MASTER-00 MASTER-00).

Plantilla

# 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:

---

DEC-001: Adopción del Documento Maestro v0.6 y reclasificación por fases

• Fecha: 2026-08-05
• Estado: APROBADA
• Hipótesis relacionadas: H01–H09 (gobernanza de investigación; ninguna validada todavía)
• Experimentos consultados: Ninguno (no se ha ejecutado ningún experimento).
• Evidencia: Documento maestro v0.6 proporcionado por el driver + auditoría de la documentación existente del monorepo (34+ archivos).
• Decisión:
  1. Adoptar MASTER-00 (docs/00_MASTER_CONTEXT.md) como documento gobernante de la cima del DAG.
  2. Crear la estructura research/ (RES-00…RES-03, EXP-01, DEC-LOG).
  3. Reclasificar los documentos existentes de producto en fases GATE_0, POC, MVP, POST_MVP (campo phase), sin reescribir su contenido.
  4. Reemplazar la secuencia de entregas M1–M4 por Gate 0 → PoC → MVP Shipaton → Producto.
• Justificación: El proyecto se trata como investigación y validación técnica (Shipaton 2026), no como producto comprometido. Mantener el catálogo completo como referencia útil sin convertirlo en alcance (§0.1, §3, §5 y DECISIÓN OFICIAL de MASTER-00).
• Alternativas rechazadas:
  • Reescribir VISION-00, SRS-830, PLAN-01, etc. para alinearlos con investigación (pérdida de detalle técnico; contra la regla de no duplicar y no reinterpretar).
  • Mantener los milestones M1–M4 como secuencia vigente (incompatible con los gates de §5).
  • Archivar los docs de producto completo fuera del grafo (pierde trazabilidad).
• Consecuencias:
  • Los docs de producto completo quedan marcados como POST_MVP / catálogo sujeto a validación.
  • VISION-00 pasa a PROPUESTA (sus KPIs, precio y personas eran afirmaciones no validadas).
  • La secuencia de entrega vigente es la de §5 de MASTER-00.
  • PROJECT.md, README.md, AGENTS.md y MANIFEST-01 se alinean con la nueva gobernanza.
• Contradicciones detectadas y resueltas:
  1. VISION-00 (hechos aprobados) vs. hipótesis H08/H09 (precio, KPIs, personas) → PROPUESTA.
  2. SRS-830, PLAN-01, TEST-01 tratan el producto completo como baseline → POST_MVP.
  3. PLAN-01 (6 spikes, roadmap v1.0) vs. secuencia Gate 0→PoC→MVP → la vigente es §5.
  4. Backend/PostgreSQL/Ktor vs. “Cloud no requerido inicialmente” → POST_MVP.
  5. MCP-SPEC (3 tools + SSE) vs. Gate 0 (2 tools + STDIO) → subconjunto anotado.
  6. PROJECT.md M1–M4 vs. gates → secuencia reemplazada.
  7. UI-MAP-00 declara “62 pantallas” vs. “34 pantallas” de MASTER-00 → discrepancia anotada como TBD.
  8. ID inconsistente preexistente: MCP-SPEC.depended_by: OPENAPI-31 vs. id real API-OPENAPI → corregido.
  9. AGENTS.md Rule 1 (consultar MCP antes de código) no aplicable hasta aprobar Gate 0 → nota de fallback añadida.
• Aspectos aún inciertos: precio definitivo, demanda real (H08/H09), UMBRAL de reducción de contexto, conteo real de pantallas (34 vs. 62).
• Fecha de revisión: TBD (tras concluir Gate 0).

---

DEC-002: Consolidación KMP Mobile + Desktop con núcleo compartido

• Fecha: 2026-08-05
• Estado: APROBADA
• Hipótesis relacionadas: H10–H14 (desktop/uso/monetización/conexión; ninguna validada todavía)
• Experimentos consultados: Ninguno (no se ha ejecutado ningún experimento). La decisión es de arquitectura y alcance, no de validación.
• Evidencia: Análisis del contexto de uso (núcleo documental pesado de edición/revisión) + arquitectura objetivo KMP §8.4 (PROPUESTA) de MASTER-00 v0.7.
• Decisión:
  1. El Mobile es la superficie de validación Shipaton (Fases A–C); el Desktop es el entorno operativo principal (Fase D).
  2. Compartir un núcleo KMP (:docugraph-core: parser YAML frontmatter, grafo, DAG, repositorios abstractos) entre Mobile, Desktop y servidor MCP.
  3. Monetización multiplataforma: RevenueCat (subscription + Paywall) en Mobile; Desktop con verificación de Pro; compra Desktop TBD.
  4. Las capacidades se asignan por plataforma (F1–F5 Mobile, DESK01–08 Desktop, CONN01–05 conexión) según §5.4–§5.6 de MASTER-00.
• Justificación: El núcleo documental no depende de UI; un único módulo compartido evita divergencia Mobile/Desktop y reduce el costo de la validación. Desktop justifica el dominio (edición profunda); Mobile lo hace accesible en la superficie Shipaton.
• Alternativas rechazadas:
  • Solo Mobile (ignora el entorno operativo real del dominio).
  • Mobile y Desktop como apps independientes sin núcleo compartido (duplicación de parser/grafo/DAG; contra Rule 4 de AGENTS.md).
  • Fase E (conexión entre dispositivos) sin evidencia previa (contra §5.6).
• Consecuencias:
  • MASTER-00 sube a v0.7; se añaden RQ11–RQ12, H10–H14, §1.6, §5.5–§5.6, §6.7–§6.8, §8.4 PROPUESTA.
  • Los documentos derivados pendientes de RES-00 §4 deben incorporar los requisitos KMP anotados.
  • Las specs de producto (US-01/BE-01/FE-01, identidad, correo) permanecen POST_MVP sin reescribirse.
• Contradicciones detectadas y resueltas:
  1. VISION-00 (monetización solo Mobile) vs. monetización multiplataforma → anotada en VISION-00 como PROPUESTA.
  2. Docs de arquitectura previos orientados solo a Android/Compose Mobile → notas de alcance multiplataforma añadidas en ARCH-03, MCP-SPEC, GLOBAL-02, UI-MAP-00.
  3. STORE_RELEASE_PLAN (solo store Mobile) vs. distribución Desktop → campo TBD en RES-00 §4.
• Aspectos aún inciertos: identidad/cuenta mínima (RevenueCat App User ID, TBD), correo transaccional (TBD), distribución Desktop (TBD), demanda real de escritorio (H11), predisposición a pago en escritorio (H12).
• Fecha de revisión: TBD (tras concluir Fase D).

---

DEC-003: Selección del Ecosistema Técnico Kotlin 2.4.10, Kotlin MCP SDK y Alineación con el Kotlin AI Benchmark

• Fecha: 2026-08-05
• Estado: APROBADA
• Hipótesis relacionadas: H04 (calidad de implementación por agentes de IA), H06 (servidor MCP en Kotlin), H10 (núcleo KMP reusable)
• Experimentos consultados: EXP-01 (diseño experimental para Gate 0 / PoC)
• Evidencia: Anuncio oficial de JetBrains (Julio/Agosto 2026) sobre Kotlin 2.4.10, lanzamiento del Kotlin AI Benchmark, SDK oficial io.modelcontextprotocol:kotlin-sdk, premio Ship Kotlin Everywhere Award en el RevenueCat Shipaton 2026 y catálogo de verificación KMP en klibs.io.
• Decisión:
  1. Adoptar Kotlin 2.4.10 como versión estándar de lenguaje y compilador K2 para todo el monorepo (:docugraph-core, :docugraph-mcp, :docugraph-app).
  2. Adoptar el Kotlin MCP SDK (io.modelcontextprotocol:kotlin-sdk:0.1.0) como librería oficial para el servidor MCP (:docugraph-mcp).
  3. Adoptar las métricas y conjuntos de datos del Kotlin AI Benchmark de JetBrains como estándar de evaluación para validar la Hipótesis H04 y el experimento EXP-01.
  4. Cumplir la Regla 5 de AGENTS.md auditando librerías KMP en klibs.io: implementar un parser de YAML Frontmatter nativo y liviano en :docugraph-core para evitar dependencias archivadas (como kaml).
  5. Inscribir la participación de DocuGraph en la categoría Ship Kotlin Everywhere Award del RevenueCat Shipaton 2026.
• Justificación: Kotlin 2.4.10 es la release de producción vigente en el ecosistema 2026. Usar el SDK oficial de MCP de JetBrains/Anthropic garantiza interoperabilidad con agentes modernos (Claude Code, Cursor, Junie). El Kotlin AI Benchmark otorga respaldo científico internacional a las métricas de evaluación de DocuGraph.
• Alternativas rechazadas:
  • Usar versiones antiguas de Kotlin sin las optimizaciones K2 de 2.4.10.
  • Implementar un servidor JSON-RPC propietario en lugar del SDK oficial de MCP.
  • Usar la librería kaml para YAML (archivada en GitHub según verificación en klibs.io).
• Consecuencias:
  • gradle/libs.versions.toml fijará kotlin = "2.4.10" y mcp-sdk = "0.1.0".
  • research/03_METRICS.md alineará las métricas §4.6 con el Kotlin AI Benchmark.
  • research/experiments/EXP-01_recuperacion_contexto.md incluirá la prueba contra el benchmark.
• Aspectos aún inciertos: disponibilidad de transportes HTTP SSE en la versión inicial del SDK (STDIO garantizado para Gate 0).
• Fecha de revisión: TBD (tras concluir Gate 0).

---

DEC-004: Actualización de dependencias a última estable y ejecución de EXP-01

• Fecha: 2026-08-11
• Estado: APROBADA
• Hipótesis relacionadas: H01–H04 (cobertura, precisión, reducción de contexto, calidad); H06 (servidor MCP en Kotlin)
• Experimentos consultados: EXP-01 (primera ejecución real, ver Resultados/Evidencia en el propio documento)
• Evidencia: Verificación directa en Maven Central / documentación oficial de cada librería (agosto 2026): kotlin-sdk 0.15.0 (SDK oficial modelcontextprotocol/kotlin-sdk, API Server/addTool/StdioServerTransport distinta a 0.1.0), kotlinx-coroutines-core 1.11.0, kotlinx-serialization-json 1.11.0, kotlinx-datetime 0.8.0, junit-jupiter 5.14.4 (línea 5.x; 6.x requiere Java 17+ y se difiere), Gradle 9.7.0 (rama 8.x EOL desde jul-2025; Kotlin 2.4.10 es compatible con Gradle 9.7 según kotlinlang.org/docs/gradle-configure-project.html).
• Decisión:
  1. Actualizar gradle/libs.versions.toml: mcp-sdk = "0.15.0", coroutines = "1.11.0", serialization = "1.11.0", datetime = "0.8.0", junit = "5.14.4"; kotlin permanece en 2.4.10 (ya vigente).
  2. Actualizar gradle/wrapper/gradle-wrapper.properties a Gradle 9.7.0.
  3. Añadir junit-platform-launcher como testRuntimeOnly (requerido explícitamente desde Gradle 9) y kotlin-sdk-testing como testImplementation en :docugraph-mcp.
  4. Implementar el código mínimo P0 de Gate 0 en :docugraph-core (loader, parser YAML nativo, grafo depends_on con Tarjan, bundle builder determinista, validador de trazabilidad) y :docugraph-mcp (servidor STDIO con get_task_context y validate_traceability, API de kotlin-sdk 0.15.0).
  5. Materializar el repositorio demo y el gold standard bajo research/evidence/ y ejecutar EXP-01 con un cliente MCP real del SDK (Client + ChannelTransport en memoria, dada la restricción de spawnear procesos STDIO externos en este entorno automatizado).
• Justificación: El SDK 0.1.0 estaba 14 versiones atrasado y su API pública (paquetes, firmas de addTool, transporte) cambió sustancialmente; mantenerlo bloqueaba la implementación de Gate 0 contra documentación vigente. Actualizar antes de implementar evita reescribir el servidor dos veces.
• Alternativas rechazadas:
  • Implementar contra el SDK 0.1.0 y posponer la actualización (arriesga una reescritura completa del servidor más adelante).
  • Saltar a Gradle 8.14.5 (último parche 8.x) en lugar de 9.7.0 (la rama 8.x está en EOL desde julio de 2025; Kotlin 2.4.10 ya soporta 9.7.0).
• Consecuencias:
  • EXP-01 pasa de EN_PRUEBA sin resultados a resultados registrados (ver sección Resultados/Evidencia del propio documento).
  • GATE_0_SPEC.md §4 actualiza el estado runtime de los 6 criterios de MASTER-00 §5.1.
  • El cliente MCP real usado es el Client oficial del SDK sobre transporte en memoria (ChannelTransport), no un proceso STDIO externo; queda documentado como limitación (MCP-G0 §5 exige “al menos un cliente real” sin especificar transporte de prueba).
• Aspectos aún inciertos: comportamiento del SDK 0.15.0 bajo transporte STDIO real con un cliente externo (Junie/Claude Code/Cursor) fuera de este entorno automatizado; umbral definitivo de reducción de contexto (pendiente de PoC multi-tarea).
• Fecha de revisión: al iniciar Fase B (PoC).

---

DEC-005: Aprobación formal de Gate 0 (criterio §5.1.1 cerrado con cliente externo real)

• Fecha: 2026-08-11
• Estado: APROBADA
• Hipótesis relacionadas: H01–H03 (cobertura, precisión, reducción de contexto — resultados ya registrados en DEC-004), H06 (servidor MCP en Kotlin), H07 (RQ12… no aplica; transporte STDIO).
• Experimentos consultados: EXP-01 (verificación externa del criterio MASTER-00 §5.1.1 con cliente MCP real, 4/4 PASS).
• Evidencia: Reporte de verificación de JetBrains Junie (2026-08-11) como cliente MCP externo vía STDIO spawneando docugraph-mcp.bat (launcher installDist, con -Dkotlin-logging.logStartupMessage=false embebido) y DOCUGRAPH_WORKSPACE=research/evidence/demo-repo: initialize correcto (serverInfo=docugraph-mcp); tools/list con get_task_context y validate_traceability; get_task_context("BE-02") -> bundle exacto BE-02→US-DEMO-01→MASTER-DEMO sin IRRELEVANT-01/BROKEN-LINK-DEMO/CYCLE-A/B; validate_traceability("...research/evidence") -> valid:false con LINK_BROKEN_DEPENDS y LINK_CYCLE; taskId inexistente -> TASK_NOT_FOUND. Reproducción manual del protocolo STDIO verificada en el monorepo con smoke test (stdout 100% JSON-RPC, exit 0).
• Decisión:
  1. Declarar el criterio MASTER-00 §5.1.1 (“el cliente se conecta correctamente”) CUMPLIDO con un cliente MCP externo real.
  2. Declarar Gate 0 formalmente APROBADO (§15 de MASTER-00; GATE-0 §6 “done de evaluación”).
  3. Resolver la incertidumbre registrada en DEC-004 (“comportamiento del SDK 0.15.0 bajo transporte STDIO real con cliente externo”).
  4. Habilitar la apertura de la Fase B (PoC, RES-00 §2).
• Justificación: MCP-G0 §5 exige “al menos un cliente real (Junie, Claude Code, Cursor, u otro compatible MCP STDIO) configurado para spawnear el proceso Gradle/JAR y listar/invocar tools”; la corrida automatizada de EXP-01 usaba el Client del SDK con ChannelTransport en memoria por restricción del entorno automatizado. Con Junie el criterio queda verificado end-to-end sobre el proceso real.
• Alternativas rechazadas: declarar Gate 0 aprobado solo con el transporte en memoria (no satisface la letra de MCP-G0 §5); posponer la aprobación sin evidencia externa (retrasa Fase B sin necesidad).
• Consecuencias:
  • EXP-01 pasa a COMPLETADA (GATE 0 APROBADO); ver su Registro de estado.
  • GATE_0_SPEC.md §8 y RES-00 §7 actualizan el veredicto final.
  • FIND-01 queda superado parcialmente por la ejecución real (checklist §3 y RQ07/H06 pasan de runtime “pendiente” a verificado para el caso demo).
• Aspectos aún inciertos: umbral numérico de reducción de contexto (se fija en PoC multi-tarea); H04 (calidad de agente) sin evaluar; get_dependency_graph (P1) y transporte HTTP/SSE (P2) fuera del alcance de Gate 0.
• Fecha de revisión: al iniciar Fase B (PoC).

---

DEC-006: Umbral mínimo de reducción de contexto de la línea base de Fase B (PoC 3 tareas)

• Fecha: 2026-08-11
• Estado: APROBADA
• Hipótesis relacionadas: H03 (reducción de contexto); H01/H02 (cobertura y precisión, ya sostenidas en 3/3 tareas).
• Experimentos consultados: EXP-02 (PoC de línea base multi-tarea: BE-02, BE-03, BE-04).
• Evidencia: Reducción de contexto observada por tarea (caracteres bundle / caracteres del contexto monolítico de research/evidence/demo-repo/, 11 documentos): BE-02 64.37%, BE-03 63.77%, BE-04 63.75% (promedio ≈ 64%). Cobertura 100%, omisión crítica 0% y precisión 100% en las 3 tareas (ver EXP-02 §Resultados). validate_traceability sobre research/evidence/ sigue detectando LINK_BROKEN_DEPENDS y LINK_CYCLE sin regresión.
• Decisión:
  1. Fijar el umbral mínimo aceptable de reducción de contexto de RES-03 §4.4 en ≥ 40%.
  2. Marcar este umbral como provisional: válido para el resto de la Fase B (PoC) sobre fixtures del repositorio demo; debe revalidarse con al menos una tarea real del catálogo de producto (docs/backend/ o docs/frontend/) antes de usarse como criterio de aceptación de MVP.
• Justificación: La línea base observada (~64%, tres tareas, baja dispersión) es muy superior al 0% (umbral mínimo trivial de “positiva” definido en EXP-01). Fijar el umbral en 40% deja margen frente a tareas reales con documentos más largos o cadenas depends_on más profundas/con bifurcaciones, que previsiblemente reducirán menos que estos fixtures sintéticos minimalistas, sin renunciar a exigir una reducción sustancial (más de un tercio del contexto).
• Alternativas rechazadas:
  • Fijar el umbral igual al valor observado (~64%): no deja margen ante la generalización a tareas reales; alto riesgo de falso negativo (H03 refutada) sin que sea un problema real del resolver.
  • Mantener el umbral en “positiva” (>0%, EXP-01): demasiado laxo para ser un criterio de aceptación útil en MVP.
  • Usar un tokenizador real en lugar de la heurística de 4 caracteres/token: se difiere por no ser crítico para la razón de reducción (mismo divisor en ambos términos); documentado como limitación en EXP-02.
• Consecuencias:
  • RES-03 §4.4 pasa de “TBD” a un umbral provisional numérico (≥40%), citando esta decisión en lugar de duplicar el valor (Regla 4 de AGENTS.md).
  • EXP-02 pasa a COMPLETADA con decisión CONTINUAR; ver su Registro de estado.
  • Próxima revisión obligatoria antes de MVP con evidencia de tareas reales.
• Aspectos aún inciertos: comportamiento de la reducción de contexto en tareas reales del catálogo de producto (documentos más largos, grafos con bifurcaciones); H04 (calidad de agente) sigue sin evaluar.
• 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.

---

DEC-007: Confirmación del umbral de reducción de contexto (≥40%) con tarea real del catálogo (BE-04)

• Fecha: 2026-08-11
• Estado: APROBADA
• Hipótesis relacionadas: H03 (reducción de contexto, ya sostenida en fixtures sintéticos por DEC-006); H01/H02 (cobertura y precisión).
• Experimentos consultados: EXP-03 (validación del umbral con BE-04, tarea real de docs/backend/).
• Evidencia: Ejecución real de get_task_context("BE-04") sobre DOCUGRAPH_WORKSPACE=docs (catálogo de producto, no fixtures): cobertura 100% (11/11 recursos del gold), precisión 100% (0 recursos irrelevantes), omisión crítica 0%. Reducción de contexto 70.17% frente al contexto completo real de docs/ (376 433 caracteres, 36 documentos) contra un bundle de 112 250 caracteres. Reducción -1.63% (negativa) frente a la simple cadena de 11 documentos (110 455 caracteres) — el bundle no comprime cada documento, solo filtra el subconjunto correcto. Gold standard pre-registrado antes de ejecutar el resolver: GOLD_STANDARD_BE-04_REAL.md.
• Decisión:
  1. Confirmar el umbral mínimo de reducción de contexto de RES-03 §4.4 en ≥ 40% (mismo valor de DEC-006, sin cambio numérico).
  2. Retirar la marca de provisional del umbral frente al comparador “bundle vs. contexto completo”: queda validado con evidencia de al menos una tarea real del catálogo de producto, cerrando la revisión pendiente anotada en DEC-006.
  3. Registrar como hallazgo adicional que el comparador “bundle vs. cadena de la tarea” puede ser negativo en tareas reales con documentos largos y concentrados (p. ej. MASTER-00 dentro de la cadena de BE-04); este comparador no es el criterio de aceptación de RES-03 §4.4, que sigue siendo “bundle vs. contexto completo”.
• Justificación: DEC-006 exigía explícitamente revalidar el umbral con al menos una tarea real de docs/backend/ o docs/frontend/ antes de usarlo como criterio de aceptación de MVP. BE-04 es una cadena real más profunda y con más bifurcaciones que los fixtures sintéticos de EXP-02, y aun así produce una reducción (70.17%) muy superior al umbral fijado, sin degradar cobertura, precisión ni omisión crítica.
• Alternativas rechazadas:
  • Subir el umbral al valor observado en EXP-03 (~70%): repetiría el mismo riesgo de falso negativo ya identificado en DEC-006 al fijar el umbral igual al valor observado en una única corrida.
  • Adoptar “bundle vs. cadena de la tarea” como comparador oficial de RES-03 §4.4 en lugar de “bundle vs. contexto completo”: mediría principalmente el overhead de renderizado del bundle, no el valor real de filtrar automáticamente el subgrafo correcto dentro de un catálogo mayor.
• Consecuencias:
  • RES-03 §4.4 mantiene el umbral ≥40%, ahora con evidencia de fixtures sintéticos (DEC-006) y de una tarea real (DEC-007).
  • EXP-03 pasa a COMPLETADA con decisión CONTINUAR; ver su Registro de estado.
  • Pendiente repetir con al menos una tarea real de docs/frontend/ para ampliar la base de evidencia antes de declarar el criterio §5.2 de MASTER-00 cumplido para MVP.
• Aspectos aún inciertos: generalización a docs/frontend/FE-0X y a cadenas con mayor profundidad/bifurcación que BE-04; H04 (calidad de agente) sigue sin evaluar; comportamiento del comparador “bundle vs. cadena” en tareas con cadenas más cortas o documentos más ligeros (podría volver a ser positivo).
• 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 de docs/frontend/.
• Nota de cierre (2026-08-11): revisión completada. EXP-04 ejecutó get_task_context("FE-04") sobre docs/frontend/FE-04_NodeInspector.md (cadena mixta frontend/backend, 15 documentos, gold pre-registrado en GOLD_STANDARD_FE-04_REAL.md): cobertura 100% (15/15), precisión 100%, omisión crítica 0%, reducción de contexto 63.90% frente al contexto completo real de docs/ (376 433 caracteres, mismo catálogo de EXP-03) contra un bundle de 135 877 caracteres — muy por encima del umbral ≥40%. Queda cerrada la pendencia de esta revisión (evidencia real de al menos una tarea de docs/frontend/ obtenida) sin cambiar el valor numérico del umbral (sin DEC-008). El criterio §5.2 de MASTER-00 se considera cumplido para MVP con evidencia real de backend (BE-04, este DEC) y frontend (FE-04, EXP-04).

---

DEC-008: Resultado EXP-05 (H04 inconclusa con hallazgo de equivalencia) y firma canónica de get_dependency_graph

• Fecha: 2026-08-11
• Estado: APROBADA
• Hipótesis relacionadas: H04 (calidad de implementación con bundle vs. monolítico).
• Experimentos consultados: EXP-05 (calidad de implementación de get_dependency_graph), protocolo H04-EVAL-PROTOCOL, EXP-03, EXP-04.
• Evidencia: Dos corridas independientes en worktrees aislados (control: contexto completo de docs/; tratamiento: solo bundle_MCP-SPEC_h04_raw.md, 136 181 caracteres, 14 documentos) de la misma tarea (get_dependency_graph(nodeId, depth) en :docugraph-core/:docugraph-mcp), calificadas a ciegas (checklist §b de H04_eval_protocol.md): empate 10/10 (100%) en ambos grupos; 0 errores de contrato, 0 reglas omitidas, 0 archivos fuera de alcance, 0 correcciones manuales; BUILD SUCCESSFUL en ambos (:docugraph-core:test :docugraph-mcp:test); 4 tests unitarios nuevos en ambos (contra + 3 vs. +2 tests de integración). Calificación ciega en EXP-05_scored.md; diffs completos en evidence/h04_{control,treatment}_diff.txt.
• Decisión:
  1. H04 → INCONCLUSA (cambio de estado registrado en RES-02): con n=1×2 y empate formal en el criterio principal, no hay evidencia de superioridad del bundle (la hipótesis literal “mejores resultados” NO se apoya); conforme a la Regla anti-sesgo un empate no se reinterpreta.
  2. Registrar hallazgo de equivalencia: con ~34% del contexto (136 181 vs. 376 433 caracteres, 63.82% de reducción), el agente alcanzó la misma calidad formal (10/10): el bundle no degrada la implementación. El hallazgo apoya la viabilidad del mecanismo, sin sustentar H04 literal.
  3. Adoptar get_dependency_graph(nodeId: String, depth: Int = 3) como firma canónica (la del enunciado, AGENTS.md y ambas corridas), declarando la discrepancia documental detectada en el pre-registro (§c del protocolo): MCP-SPEC §4.2 y ARCH-03 §2.3 describen workspacePath (grafo completo, delega en BE-03). Queda pendiente actualizar esos dos documentos de catálogo para alinear la firma; se registra aquí porque la herramienta ya tiene candidata de implementación real.
  4. Disponibilizar las dos implementaciones (worktrees docugraph-h04-control/docugraph-h04-treatment) como candidatas a adoptar la tool P1 del PoC (GATE_0_SPEC §7) en main; se evaluará cuál integrar en una tarea de consolidación posterior.
• Justificación: el experimento fue diseñado y calificado bajo el protocolo anti-sesgo pre-registrado; el resultado (empate) no soporta la hipótesis literal, y forzarlo sería reinterpretar evidencia en contra de RES-03 “Regla anti sesgo”. La equivalencia con menos de un tercio del contexto es un resultado de investigación útil para Fase B.
• Alternativas rechazadas:
  • Declarar H04 APOYADA por el empate: reinterpretaría un resultado neutral como positivo, violando la regla anti-sesgo.
  • Declarar H04 REFUTADA: no hay degradación atribuible al bundle (0 incumplimientos en ambos), por lo que tampoco se apoya la refutación.
  • Mover umbral o métricas §4.6: no procede; ninguna métrica se modifica después de conocer resultados.
• Consecuencias:
  • RES-02 H04 → INCONCLUSA; EXP-05 pasa a COMPLETADA; H04-EVAL-PROTOCOL queda APROBADA con depended_by: [EXP-05].
  • get_dependency_graph pasa de “no implementada” a “con dos implementaciones candidatas en worktrees” (P1 del PoC).
  • Queda pendiente reconciliar MCP-SPEC §4.2 y ARCH-03 §2.3 con la firma canónica nodeId/depth.
• Aspectos aún inciertos: generalización a otras tareas/dominios (n=1); posible fuga de cegado a nivel de sesión (documentada en EXP-05); modelo de agente usado por grupo no aislado en sesiones distintas con el mismo ejecutor.
• Nota de cierre (2026-08-11): revisión cumplida — la tool quedó consolidada en main. Se integró la implementación del worktree tratamiento (verificada: 21 tests en verde, :docugraph-core:test :docugraph-mcp:test, incluidas las 2 pruebas de integración; smoke test STDIO real con nodeId=BE-04, depth=2 → 15 nodos/34 aristas, truncated=true). Además, se reconciliaron MCP-SPEC §4.2 y ARCH-03 §2.3 con la firma canónica nodeId/depth (pendencia declarada en §239), quedando las tres fuentes documentales (AGENTS.md, MCP-SPEC, ARCH-03) alineadas. get_dependency_graph pasa de “candidata en worktrees” a tool P1 implementada en main (GATE_0_SPEC §7).

---

DEC-009: Gate de integración de la aplicación (§5.3) — Plan B (demostración verificable) como base del MVP móvil

• Fecha: 2026-08-12
• Estado: APROBADA (veredicto recomendado; decisión final de negocio pendiente del dueño del producto, ver “Aspectos aún inciertos”)
• Hipótesis relacionadas: ninguna hipótesis de investigación (H01–H14) evalúa directamente Plan A vs. Plan B; la decisión es de alcance/arquitectura del gate §5.3 de MASTER-00, análoga en naturaleza a DEC-002.
• Experimentos consultados: EXP-01, EXP-02, EXP-03, EXP-04 (evidencia de que get_task_context/get_dependency_graph ya funcionan de forma determinista y verificable, pero solo se han ejecutado vía STDIO con un cliente MCP de escritorio — Junie — nunca desde una app móvil/Compose).
• Evidencia:
  1. MASTER-00 §5.3 define el gate como una elección entre Plan A (la app consume resultados reales del servidor MCP en tiempo real) y Plan B (la app muestra bundles generados previamente por la PoC, identificados como precalculados, con evidencia separada del MCP funcional).
  2. MASTER-00 §7 fija explícitamente “Cloud: No requerido inicialmente” (decidido) y Desktop/backend relacional (:docugraph-backend) como POST_MVP/sin equivalente inicial — es decir, no existe hoy ningún servicio remoto que una app móvil pueda invocar en vivo sin construir infraestructura nueva fuera de alcance.
  3. :docugraph-mcp (DEC-005) solo ha sido verificado como servidor STDIO local, spawneado por un cliente de escritorio (Junie) sobre el mismo sistema de archivos; no expone hoy transporte HTTP/SSE ni ningún endpoint alcanzable desde un proceso Android/iOS empaquetado (MCP-SPEC documenta SSE como POST_MVP, fuera de Gate 0/PoC).
  4. AGENTS.md (Módulos) prohíbe a este agente tocar :docugraph-core y :docugraph-mcp; Plan A requeriría como mínimo exponer un transporte de red nuevo en :docugraph-mcp y/o levantar :docugraph-backend, ambos fuera del alcance autorizado de esta sesión y de MASTER-00 §7.
  5. MASTER-00 §5.3 exige explícitamente que Plan B identifique los resultados como precalculados y muestre evidencia separada del MCP funcional — la evidencia de ese MCP funcional ya existe y está aprobada (DEC-005, Gate 0 aprobado; DEC-006/DEC-007/EXP-04, PoC con reducción de contexto 63–70% en tareas reales), por lo que Plan B no exige generar evidencia nueva, solo reutilizar la existente citándola.
  6. Existen bundles reales precalculados en research/evidence/ (p. ej. bundle_BE-02_raw.md sobre research/evidence/demo-repo/, cadena BE-02 → US-DEMO-01 → MASTER-DEMO) listos para mostrarse en una pantalla S03 sin trabajo adicional de generación.
• Decisión:
  1. Adoptar Plan B (demostración verificable) como base del MVP móvil para el gate §5.3 de MASTER-00.
  2. La app (:docugraph-app) mostrará bundles generados previamente por la PoC/Gate 0 (research/evidence/), identificados en la UI como resultados precalculados, sin presentarlos como ejecución en vivo (condición explícita de MASTER-00 §5.3).
  3. La evidencia del servidor MCP funcional se mantiene separada de la app: el video/demostración del MVP citará DEC-005 (Gate 0 aprobado, cliente STDIO real) y EXP-02/EXP-03/EXP-04 (PoC) en vez de duplicar esa evidencia dentro de la app.
  4. No se implementa en esta sesión ningún transporte de red nuevo en :docugraph-mcp ni backend (:docugraph-backend); ambos permanecen fuera de alcance del MVP Shipaton (§5.4/§7 de MASTER-00).
  5. Se marca el Gate de integración de la app (PROJECT.md, RES-00 §2) como APROBADO con este veredicto, habilitando el objetivo B (esqueleto de :docugraph-app) de esta misma iniciativa.
• Justificación: Plan A exigiría (a) exponer :docugraph-mcp por un transporte alcanzable desde un dispositivo móvil empaquetado —fuera del alcance Gate 0/PoC y de los módulos que este agente puede tocar—, y/o (b) levantar :docugraph-backend/Cloud, explícitamente “no requerido inicialmente” por §7 de MASTER-00; ambas rutas introducen riesgo de fallo en vivo durante la demo (red, latencia, estado del servidor) sin evidencia previa de que ese camino haya sido siquiera probado. Plan B, en cambio, reutiliza evidencia ya validada (Gate 0 aprobado, PoC con reducción de contexto ≥40% confirmada dos veces con tareas reales) sin trabajo de infraestructura nuevo, cumple la condición de honestidad exigida por MASTER-00 §5.3 (rotulado explícito + evidencia separada) y no bloquea Fase D (Desktop), donde sí se planea “ejecución MCP” real (§5.5).
• Alternativas rechazadas:
  • Plan A puro (la app invoca :docugraph-mcp en vivo): rechazado por riesgo de demo en vivo (dependencia de red/proceso), por requerir tocar módulos fuera del alcance de esta sesión (:docugraph-mcp/:docugraph-backend) y por contradecir “Cloud no requerido inicialmente” (§7).
  • Plan A con MCP embebido localmente en el dispositivo (sin red, spawneando el proceso Kotlin dentro de la app móvil): descartado por inviabilidad práctica en Android/iOS empaquetado (requiere JVM/proceso Kotlin embebido no evaluado, fuera de alcance de Gate 0/PoC) y por no aportar valor de validación adicional frente a Plan B en esta fase.
  • Híbrido (Plan B en MVP + Plan A oculto tras flag experimental): descartado por ahora para no introducir complejidad ni superficie de fallo no auditada antes de tener Fase D (Desktop) como entorno operativo real; puede reconsiderarse post-MVP con evidencia.
• Consecuencias:
  • PROJECT.md (Delivery Gates) actualiza el estado del “Gate de integración de app” de BACKLOG a APROBADO (DEC-009): Plan B.
  • RES-00 §2 y §7 registran el veredicto Plan B como cierre del gate §5.3.
  • Queda habilitado el objetivo B de esta iniciativa: esqueleto de :docugraph-app con la pantalla S03 mostrando un bundle precalculado real (bundle_BE-02_raw.md), rotulado explícitamente como resultado precalculado.
  • Fase D (Desktop, §5.5 de MASTER-00) permanece como el momento previsto para “ejecución MCP” real; esta decisión no la adelanta ni la descarta.
• Aspectos aún inciertos: esta es una decisión de alcance técnico/arquitectura tomada por el agente con la evidencia documental disponible, no una decisión de negocio/marketing (p. ej. si el dueño del producto prefiere asumir el riesgo de una demo en vivo por impacto narrativo). La decisión final sobre Plan A vs. Plan B para el video de sumisión del Shipaton queda marcada como pendiente de aprobación del dueño del producto; mientras tanto, Plan B es el veredicto recomendado y el que desbloquea el objetivo B sin bloqueo alguno.
• Fecha de revisión: antes de enviar el video final de sumisión del Shipaton (MVP Shipaton, §5.4 de MASTER-00), o al iniciar Fase D (Desktop) si se reconsiderara ejecución en vivo.

---

DEC-010: RevenueCat real obligatoria para el Shipaton y foco de publicación en Google Play (Android)

• Fecha: 2026-08-13
• Estado: APROBADA
• Hipótesis relacionadas: H09 (disposición a pagar; sigue SIN_PROBAR y no se presenta como evidencia); H14 (conservación del entitlement entre plataformas; no evaluada en este ciclo).
• Experimentos consultados: ninguno; es una decisión de alcance/requisito externo (eligibilidad Shipaton) y de restricción de plataforma, análoga en naturaleza a DEC-009.
• Evidencia:
  1. Reglas oficiales del RevenueCat Shipaton 2026 (Devpost, revenuecat-shipaton-2026.devpost.com/rules): la elegibilidad exige una app publicada en App Store, Google Play o Samsung Galaxy Store entre 1-ago y 30-sep-2026, con el SDK de RevenueCat alimentando al menos una compra in-app o web real. La sumisión incluye URL de la app publicada, video demo ≤2 min, icono 1024×1024 y screenshot 1179×2556; sin trial gratis, se exige promo code para que los jueces prueben el Pro.
  2. Restricción de plataforma del driver (2026-08-13): solo dispone de Windows y dispositivos Android; sin macOS no puede firmar/archivar ni publicar iOS.
  3. La categoría Ship Kotlin Everywhere (JetBrains) exige URLs en vivo de App Store y Google Play (ambas); la categoría Next Gen exige ser estudiante activo matriculado (no aplica a recién graduados).
  4. El Ship Kit de RevenueCat rastrea hitos que incluyen “primera compra real”, reforzando que la integración de tienda es parte del requisito, no opcional.
• Decisión:
  1. Integrar RevenueCat real (compra en Google Play) en el MVP: reemplazar el DemoRevenueCatGateway por purchases-kmp conectado a un producto de suscripción Pro configurado en RevenueCat y Play Console, conservando los tests de no-concesión indebida.
  2. Enfoque de publicación: Google Play (Android) únicamente para el Shipaton; iOS se difiere por falta de macOS.
  3. Renunciar explícitamente a las categorías Ship Kotlin Everywhere (requiere iOS) y Next Gen (requiere estudiante activo). Categorías objetivo: Grand Prize, HAMM, RevenueCat Design, Peace Prize y #BuildInPublic.
  4. El proyecto se mantiene como herramienta personal del driver, independiente del resultado del Shipaton.
  5. Plan B se conserva intacto (DEC-009): los bundles se muestran precalculados y la evidencia MCP permanece separada; la eligibilidad no depende de ello.
• Justificación: sin RevenueCat real no hay sumisión elegible (requisito contractual del evento); sin macOS no es publicable iOS en este ciclo; publicar solo Android satisface los requisitos base y mantiene al proyecto utilizable personalmente.
• Alternativas rechazadas:
  • iOS vía CI en la nube (Codemagic/GitHub Actions): requiere cuenta Apple Developer ($99/año), certificados y, sin ningún dispositivo Apple para probar, alto riesgo de publicar una app rota; se difiere.
  • Categoría Next Gen: no elegible (el driver es recién graduado, no estudiante activo matriculado).
  • Diferir la integración de RevenueCat hasta validar H09: bloquearía la sumisión; la integración no implica presentar H09 como evidencia.
• Consecuencias:
  • REVENUECAT-PLAN deja de tratar la conexión real como TBD/opcional para el MVP Shipaton; se actualiza para reflejar Google Play como tienda objetivo.
  • STORE-RELEASE-PLAN se actualiza: publicación Android en Google Play con producto Pro y promo code para jueces; Desktop y iOS quedan fuera del ciclo Shipaton.
  • El gateway determinista se mantiene como interfaz (RevenueCatGateway) para tests y como fallback demo, con la implementación real detrás.
  • Requiere cuenta de desarrollador de Google Play ($25 única vez), configuración del producto Pro y revisión de la app.
• Aspectos aún inciertos: tiempo de revisión de Google Play antes del deadline (30-sep-2026); identidad/cuenta mínima (TBD) y precio definitivo de Pro (TBD); resultado de H09 (disposición a pago) permanece sin evidencia.
• Fecha de revisión: antes del 30-sep-2026 (deadline de sumisión) o al reconsiderar iOS/Fase D.

---

DEC-011: Congelamiento del objetivo Shipaton 2026 y reorientación a herramienta personal del driver

• Fecha: 2026-08-13
• Estado: APROBADA
• Hipótesis relacionadas: ninguna hipótesis de investigación cambia de estado; la decisión es de gobernanza/alcance (orientación del proyecto), análoga en naturaleza a DEC-009 y DEC-010.
• Experimentos consultados: los ya ejecutados (EXP-01…EXP-05) siguen siendo la base técnica validada; la decisión no genera evidencia nueva.
• Evidencia:
  1. Declaración del driver (2026-08-13): DocuGraph pasa a ser su herramienta personal de trabajo diario para sus proyectos (documentación atómica, contexto MCP por tarea, seguimiento del grafo), avanzando “de las bases a lo avanzado”.
  2. El objetivo Shipaton 2026 queda congelado: no se persigue el deadline de sumisión (30-sep-2026). DEC-009/DEC-010 quedan registradas como histórico de alcance, sin descartarse.
  3. La base validada (Gate 0 aprobado, PoC con reducción 63–70%, tools MCP funcionando por STDIO) es el activo que sostiene el uso personal; no depende del resultado del Shipaton.
• Decisión:
  1. Congelar el objetivo Shipaton 2026 como meta de entrega: no se realiza publicación en tiendas ni video de sumisión en este ciclo. Nada se elimina: toda la documentación y decisiones quedan en el grafo como histórico trazable.
  2. Reorientar DocuGraph como herramienta personal del driver para la gestión de sus proyectos (creación → uso → seguimiento de tareas documentadas), avanzando por niveles desde las fundaciones hasta lo avanzado.
  3. Definir el roadmap del proyecto definitivo en un documento nuevo ROADMAP-00 (orden base → avanzado), que orienta el trabajo futuro con Junie.
  4. La integración RevenueCat/Google Play de DEC-010 queda suspendida (no es gate del uso personal); el código permanece pero no se persigue su configuración ni publicación.
  5. Las capacidades Fase D (Desktop) y el ciclo de edición (tool de escritura MCP) pasan a ser prioridad del roadmap personal en lugar de metas del Shipaton.
• Justificación: el valor real para el driver es el ciclo documentación→contexto→tareas, ya validado; el Shipaton fue un vehículo de validación técnicamente cumplido (Gate 0 y PoC). Publicar en tiendas y configurar RevenueCat real requiere infraestructura (macOS, cuentas, revisión de tiendas) que no aporta valor al uso personal inmediato.
• Alternativas rechazadas:
  • Seguir persiguiendo el Shipaton (publicación en tiendas + RevenueCat real): exige infraestructura externa y tiempo que se priorizan ahora al uso personal.
  • Abandonar el repo: la base validada tiene valor diario demostrable (MCP + núcleo documental).
  • Reorientar sin registrar decisión: violaría la gobernanza de MASTER-00 (§10, §15) y la Regla 4 de AGENTS.md.
• Consecuencias:
  • MASTER-00 actualiza su estado/naturaleza y la “DECISIÓN OFICIAL” (§estado y §DECISIÓN OFICIAL), añadiendo el roadmap de herramienta personal.
  • Se crea ROADMAP-00 como documento de orientación del proyecto definitivo.
  • RES-00 marca el Shipaton como congelado e incorpora la referencia al roadmap personal.
  • AGENTS.md actualiza su orientación (de “research/technical validation Shipaton” a herramienta personal).
  • La app y el servidor MCP permanecen como están; el trabajo posterior se guía por ROADMAP-00.
• Aspectos aún inciertos: prioridad exacta de los niveles del roadmap; si el driver usará Desktop como superficie principal o solo MCP + editor de código; H08/H09/H13 dejan de ser críticas para el uso personal (quedan sin evidencia, registradas).
• Fecha de revisión: al completar el Nivel 1 de ROADMAP-00, o cuando el driver decida retomar el Shipaton/mercado.

---

DEC-012: Superficie exclusiva Desktop y eliminación de pagos y targets móviles

• Fecha: 2026-08-13
• Estado: APROBADA
• Hipótesis relacionadas: ninguna hipótesis de investigación cambia de estado; es una decisión de alcance/arquitectura de la herramienta personal, análoga en naturaleza a DEC-011.
• Experimentos consultados: los ya ejecutados (EXP-01…EXP-05) siguen siendo la base técnica validada; la decisión no genera evidencia nueva.
• Evidencia:
  1. Declaración del driver (2026-08-13): para su uso personal, DocuGraph se enfocará exclusivamente en la superficie Desktop (jvm("desktop")); no se usará el flujo de pagos.
  2. DEC-011 ya había suspendido la integración RevenueCat/Google Play de DEC-010 (publicación en tiendas no es gate del uso personal).
  3. El valor diario del driver es el ciclo documentación → contexto MCP → tareas sobre la máquina local (Desktop/STDIO), validado en DEC-005/DEC-006/DEC-007/EXP-04.
  4. Los targets móviles (androidTarget, iosArm64, iosSimulatorArm64), el esqueleto móvil (androidMain/iosMain) y las pantallas demo/Plan B del MVP móvil (DemoBundle*, S10–S12) dejan de tener uso en la herramienta personal.
• Decisión:
  1. Eliminar los targets Android e iOS de :docugraph-app (build multi-target móvil, androidMain/, iosMain/), dejando únicamente el target Desktop JVM.
  2. Eliminar el código de pagos de la app: interfaz RevenueCatGateway, DemoRevenueCatGateway, factories expect/actual, pantallas paywall S10–S12 (F5), su test y las dependencias RevenueCat de Gradle.
  3. Eliminar las pantallas demo del MVP móvil (S01–S09 sin gateway y DemoBundleData/DemoBundleScreen): la app Desktop trabaja solo con datos reales del workspace vía WorkspaceGateway.
  4. Mantener el contrato WorkspaceGateway + WorkspaceGatewayReal (datos reales) como única ruta de UI; DocuGraphApp pasa a exigir un gateway no-nulo.
  5. Actualizar MASTER-00, ROADMAP-00, AGENTS.md y los planes afectados (REVENUECAT-PLAN, STORE-RELEASE-PLAN) para reflejar el foco Desktop sin pagos.
• Justificación: la app móvil y el paywall fueron un objetivo del Shipaton (congelado en DEC-011) y no aportan valor al uso personal del driver; su mantenimiento añade complejidad de build (AGP, SDK móvil, RevenueCat) sin contrapartida. Desktop es la única superficie que el driver necesita y la que ejecuta el MCP real (§5.5 de MASTER-00).
• Alternativas rechazadas:
  • Mantener el esqueleto móvil y el paywall sin usar (complejidad de build y de código muerto en la herramienta personal).
  • Solo desactivar RevenueCat sin eliminar targets móviles (el build multi-target sigue exigiendo AGP y configuración Android).
• Consecuencias:
  • :docugraph-app queda como app Desktop (Compose Multiplatform para JVM) sin dependencias de RevenueCat ni configuración Android.
  • ROADMAP-00 Nivel 3.2 (app móvil de supervisión) queda fuera del foco actual; Nivel 3.1 (Desktop) pasa a ser la superficie única.
  • REVENUECAT_PLAN y STORE_RELEASE_PLAN pasan a histórico (sin implementación activa).
  • Las decisiones DEC-009/DEC-010 permanecen en el grafo como histórico trazable (nada se borra).
• Aspectos aún inciertos: si el driver retomará alguna vez una superficie móvil (quedaría como trabajo futuro si decide revivir el esqueleto); foco real del incremento 2 de Desktop.
• Fecha de revisión: al completar el Nivel 3.1 de ROADMAP-00, o cuando el driver decida reconsiderar una superficie móvil/pagos.

---

DEC-013: Arquitectura self-hosted gratuita — Obsidian + MCP remoto + Gitea + visor web (Oracle Always Free)

• Fecha: 2026-08-14
• Estado: APROBADA
• Hipótesis relacionadas: ninguna hipótesis de investigación cambia de estado; es una decisión de arquitectura/alcance de la herramienta personal del driver, análoga en naturaleza a DEC-011 y DEC-012.
• Experimentos consultados: los ya ejecutados (EXP-01…EXP-05) siguen siendo la base técnica validada; la decisión no genera evidencia nueva.
• Evidencia:
  1. Declaración del driver (2026-08-14): DocuGraph debe seguir siendo 100% gratuita (uso personal) y self-hosted; el driver dispone de una instancia Oracle Cloud Always Free (2 OCPU, 12 GB RAM) para alojar servicios propios.
  2. Evaluación de “Notion + Notion MCP” como superficie: la UX de Notion sería deseable (tipo Word/Notion), pero consultar data sources exige plan Enterprise + Notion AI (pago), y el hosted MCP opera a nivel página con OAuth (sin headless), por lo que no satisface el requisito de gratuidad y auto-hospedaje.
  3. El driver confirmó (2026-08-14) que todo se escribe en Markdown/Mermaid y que la escritura de documentos la hacen los agentes vía MCP (Claude Code, Codex, Antigravity); la app Desktop de edición manual (S04 crear, S05 editar) contradice ese flujo.
  4. La UX tipo Notion/Word ya existe, es gratis y local y lee .md nativo con vista de grafo y soporte Mermaid: Obsidian.
  5. El server :docugraph-mcp ya implementa los 8 tools de la matriz (AGENTS.md) por STDIO; el SDK kotlin-sdk 0.15.0 soporta transporte remoto (SSE/HTTP) para exponerlo desde Oracle.
• Decisión:
  1. Fuente de verdad: Markdown + git (sin cambio): los .md atómicos en un repo git son la única fuente; nada se escribe en la nube de un tercero.
  2. Superficie de lectura/edición local: Obsidian (gratis, markdown nativo, grafo integrado, Mermaid); reemplaza la UX de edición del Desktop actual. El driver no edita vía UI propietaria.
  3. Escritura de documentos: solo agentes vía MCP (:docugraph-mcp), que validan el DAG antes de escribir (upsert_document, update_frontmatter).
  4. Oracle Cloud Always Free aloja: (a) el server MCP por SSE/HTTP (accesible por los agentes desde cualquier lugar), (b) Gitea (remote git propio del driver), (c) un visor web de la documentación (render de los .md + grafo) para consulta desde navegador/móvil.
  5. Retirar gradualmente la app Desktop como editor: queda como vista read-only/fallback hasta que Obsidian + visor web cubran el flujo; el esfuerzo se vuelca al server MCP y al visor web.
• Justificación: el driver necesita UX tipo Notion/Word, escritura por agentes y gratuidad total; Notion no cumple el requisito de precio (Enterprise para data sources) ni de auto-hospedaje. Obsidian proporciona la UX local gratis sobre el mismo .md, y Oracle (ya pagado: Always Free) permite exponer el MCP de forma remota y un git y visor web propios sin costo adicional. El Desktop actual se descarta como editor porque la escritura manual en GUI contradice el flujo real del driver.
• Alternativas rechazadas:
  • Notion + Notion MCP como superficie única: exige plan Enterprise + Notion AI para consultar data sources (pago), OAuth no headless, y lock-in en la nube de un tercero.
  • Construir un editor tipo Notion/Word en Compose Desktop: costo alto (render markdown/mermaid, editor WYSIWYG) sin aportar valor frente a Obsidian ya existente.
  • Solo desktop actual (S01–S10) como única superficie: la edición manual contradice el flujo “escriben los agentes vía MCP” y su UX fue rechazada por el driver.
• Consecuencias:
  • ROADMAP-00 se reestructura: el Nivel 3.1 (Desktop) pasa a “vista/lectura read-only” y se añade un nivel para el ecosistema self-hosted (MCP remoto, Gitea, visor web, Obsidian).
  • MASTER-00 actualiza estado, estrategia de superficie, §7 (stack) y §5.5 (Desktop pasa a vista).
  • El server MCP requiere añadir transporte SSE/HTTP al :docugraph-mcp (fase 1 de trabajo inmediato).
  • La app Desktop (:docugraph-app) deja de ser la prioridad de UI; su código permanece como histórico/fallback.
• Implementación concreta (2026-08-14): se selecciona Gitea en Oracle como remoto central, un checkout Oracle separado como workspace del MCP, Caddy como barrera X-MCP-API-KEY, MkDocs Material como visor y un exportador Kotlin basado en DocGraphWorkspace. El flujo fail-closed es pull → escritura MCP → validate_traceability → revisión → commit/push; no existe sincronización automática destructiva.
• Evidencia de implementación: deploy/oracle/compose.yaml, deploy/oracle/Caddyfile, deploy/oracle/scripts/, mkdocs.yml, deploy/viewer/, GraphExportMain y los tests de :docugraph-mcp. La validación local de build/tests/configuración pasó; la aplicación de la nueva pila y smoke tests autenticados en Oracle quedan pendientes.
• Aspectos aún inciertos: dominio definitivo y secreto operativo de Oracle, configuración final del repositorio Gitea y resultado del smoke test HTTP autenticado tras reiniciar la pila remota.
• Fecha de revisión: después de activar Compose en Oracle y guardar la evidencia de autenticación, persistencia, sincronización y visor sin secretos.

---

DEC-014: Retirada de la aplicación Desktop y consolidación del perfil self-hosted

• Fecha: 2026-08-14
• Estado: APROBADA
• Hipótesis relacionadas: ninguna hipótesis cambia de estado; es una decisión de alcance y mantenimiento derivada de DEC-013.
• Evidencia:
  1. DEC-013 estableció que la escritura estructurada la realizan los agentes vía MCP y que Obsidian, Gitea y el visor web cubren la lectura y revisión.
  2. El módulo :docugraph-app ya no aporta una capacidad necesaria al flujo operativo y mantiene dependencias Compose fuera del perfil self-hosted.
  3. El núcleo documental y el servidor MCP no dependen de código de UI; la eliminación puede verificarse construyendo :docugraph-core y :docugraph-mcp.
• Decisión:
  1. Eliminar :docugraph-app, sus fuentes, tests, inclusión Gradle y plugins Compose no utilizados.
  2. Mantener las especificaciones FE-XX, las decisiones Mobile/Desktop y el catálogo Shipaton como documentación histórica trazable, sin presentarlos como módulos activos.
  3. Establecer Obsidian, Gitea y MkDocs como superficies humanas oficiales, y :docugraph-core/:docugraph-mcp como módulos activos.
• Justificación: retirar una aplicación que no participa en el flujo real reduce mantenimiento, dependencias y ambigüedad arquitectónica sin eliminar la evidencia histórica del proyecto.
• Alternativas rechazadas:
  • Mantener la app como fallback: duplicaría las superficies de lectura y conservaría una dependencia de UI no utilizada.
  • Borrar las especificaciones frontend y decisiones previas: destruiría trazabilidad histórica innecesariamente.
• Consecuencias:
  • settings.gradle.kts solo incluye :docugraph-core y :docugraph-mcp.
  • El catálogo y las especificaciones antiguas se etiquetan documentalmente como históricos cuando describen la app o el backend retirados.
  • El build activo deja de resolver plugins y versiones Compose.
• Fecha de revisión: si el driver decide reintroducir una aplicación después de reunir evidencia de valor operativo.

---

DEC-015: Frontera operativa reproducible para Oracle y el viewer

• Fecha: 2026-08-14
• Estado: APROBADA
• Hipótesis relacionadas: ninguna hipótesis cambia de estado; es una decisión operativa y de publicación.
• Evidencia: el checkout seleccionado con README.md, AGENTS.md, PROJECT.md, mkdocs.yml, javascripts/ y docs/ produjo nodeCount=47, edgeCount=170, errors=[] y valid=true; el viewer generó MkDocs y /graph/ sin warnings. El builder usa un staging operativo separado también para GraphExportMain, evitando que una ejecución desde el monorepo incluya investigación o fixtures.
• Decisión:
  1. Oracle publica un workspace Git sparse-checkout explícito; investigación, fixtures, .agents, código fuente y artefactos de build quedan fuera del grafo operativo.
  2. MkDocs se construye desde un staging temporal de ese mismo contenido y build-site.sh falla si el graph.json no es válido.
  3. La evidencia histórica autenticada registra 200 para las operaciones MCP y la verificación actual registra 401 sin credencial o con una credencial incorrecta; el smoke autenticado vigente, la sincronización de un documento y la persistencia siguen pendientes hasta ejecutar la pila con credenciales locales en Oracle.
• Justificación: separar el catálogo operativo de los artefactos históricos permite mantener las reglas de validación intactas y hacer que MCP y el viewer consuman el mismo conjunto reproducible.
• Aspectos aún inciertos: resultado del smoke autenticado posterior a la actualización del checkout, visibilidad del documento de prueba en las tres superficies y persistencia tras reinicio.
• Fecha de revisión: después de completar el smoke autenticado actual, la sincronización y la persistencia, y actualizar REMOTE_SELF_HOSTED_CHECKLIST.md con la evidencia correspondiente.