Saltar a contenido

OpenClaw Document Architecture Review

Fecha: 2026-06-10

Modo: GOVERNANCE + INVENTORY

Alcance: auditoria documental de OpenClaw y propuesta de formalizacion liviana.

Restricciones aplicadas:

  • sin runtime
  • sin VPS
  • sin Docker
  • sin queries
  • sin codigo
  • sin mover, renombrar ni borrar documentacion
  • sin reestructuracion masiva

Read-set aplicado

Se leyeron completos los documentos rectores cortos:

  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/governance/GATE-CODEX-EFFICIENCY.md
  • docs/governance/README.md
  • docs/governance/INDEX.md
  • docs/governance/GOVERNANCE-CONTROL-TOWER.md
  • mkdocs.yml
  • docs/tenants/alpuntodeventa/business-observer/README.md
  • docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-GOVERNANCE-MODEL.md

Se aplico lectura selectiva de docs/PROJECT-STATE.md y docs/ROADMAP.md por ser documentos grandes. La lectura se centro en encabezados, secciones de autoridad documental, estado vigente, Business Observer y roadmap. Esto cumple GATE-CODEX-EFFICIENCY.md: evitar archivos grandes completos cuando alcanza con indice, busqueda y muestras representativas.

Inventario documental general

Conteo aproximado previo a este paquete documental:

  • Markdown total en repo: 284
  • Markdown bajo docs/: 268
  • Markdown fuera de docs/: 16

Distribucion principal bajo docs/:

Area Cantidad aproximada
docs/governance 154
docs/tenants 73
raiz docs/ 26
docs/prompts 6
docs/architecture 4
docs/business 4
docs/global 1

Directorios documentales principales:

  • docs/governance/: autoridad documental viva del VPS, reglas, catalogos, validacion, operaciones, seguridad, servicios y runbooks.
  • docs/governance/knowledge/: plataforma de conocimiento, diagramas, observabilidad, Docker, runtime e infraestructura.
  • docs/governance/operations/: baselines, control tower operativo, sandbox, monitoreo, mantenimiento y politicas de update.
  • docs/governance/security/: estado, politicas y runbooks de seguridad.
  • docs/governance/catalog/: catalogos maestros de servicios, redes, volumenes, dominios, puertos, backups, tests, usuarios y secretos.
  • docs/architecture/: fundacion multi-tenant, data foundation, API platform y API documentation platform.
  • docs/business/: vision global del Business Observer y casos de uso core.
  • docs/tenants/: documentacion por tenant.
  • docs/tenants/alpuntodeventa/business-observer/: capa funcional y de datos del Business Observer APV.

Indices existentes:

  • docs/index.md: entrada general del portal.
  • mkdocs.yml: navegacion publicada del Knowledge Portal.
  • docs/governance/README.md: entrada de governance.
  • docs/governance/INDEX.md: indice operativo de governance.
  • docs/governance/knowledge/README.md: entrada Knowledge Platform.
  • docs/governance/operations/README.md: entrada operacional.
  • docs/tenants/README.md: entrada tenants.
  • docs/tenants/alpuntodeventa/README.md: entrada tenant APV.
  • docs/tenants/alpuntodeventa/business-observer/README.md: entrada Business Observer APV.

Roadmaps existentes:

  • docs/ROADMAP.md: roadmap global historico y futuro.
  • docs/FUTURE-PLATFORM-ROADMAP.md: vision futura oficial.
  • docs/tenants/alpuntodeventa/business-observer/ROADMAP.md: roadmap tenant del Business Observer APV.

Project states existentes:

  • docs/PROJECT-STATE.md: estado global certificado y evidencia historica.
  • docs/tenants/alpuntodeventa/business-observer/PROJECT-STATE.md: estado del observer APV.
  • docs/governance/GOVERNANCE-CONTROL-TOWER.md: lectura ejecutiva de governance.
  • docs/governance/VALIDATION-STATE.md: estado de validacion.

Areas cubiertas:

  • Governance: fuerte, con reglas, contratos, change gates, control tower, catalogos, servicios, runbooks y validacion.
  • Knowledge: fuerte, con plataforma O6/O8/O9, diagramas, catalogos, runtime e infraestructura.
  • Architecture: buena, con documentos rectores multi-tenant, data foundation, API platform y API documentation platform.
  • Operations: fuerte, con baseline, monitoreo, mantenimiento, update policy y sandbox operations.
  • Observability: fuerte, con catalogos y fichas de Prometheus, Grafana, Alertmanager, exporters y Thanos.
  • Runtime: documentado como conocimiento y fichas, pero no tocado en esta auditoria.
  • Testing: cubierto por VALIDATION-STATE, REGRESSION-MATRIX, catalog/TESTS.md y evidencias historicas.
  • Tenants / Business Observer: fuerte para APV, incipiente para otros tenants.

Documento rector

Veredicto al inicio de esta auditoria: PARCIAL.

No existia un Project Constitution corto y explicito antes de este paquete.

Evidencia de autoridad parcial:

  • CODEX.md funciona como contrato operativo raiz para sesiones con Codex.
  • ACTIVE-CONTEXT.md funciona como router operativo corto.
  • docs/governance/ se declara como autoridad documental viva del VPS.
  • docs/governance/INDEX.md funciona como indice de governance.
  • mkdocs.yml funciona como indice navegable del portal publicado.
  • docs/PROJECT-STATE.md contiene una seccion de autoridad documental vigente.
  • BUSINESS-OBSERVER-GOVERNANCE-MODEL.md funciona como autoridad funcional oficial del Business Observer APV.

Lo que faltaba:

  • una constitucion de proyecto de menos de una pagina
  • una jerarquia documental formal y liviana
  • una regla explicita para ubicar futuros blueprints sin duplicar definiciones
  • una separacion clara entre constitucion, contrato operativo, estado, roadmap, governance, blueprints, contratos, diseno y evidencia

Jerarquia documental actual

Documentos raiz actuales:

  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/governance/README.md
  • docs/governance/INDEX.md
  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/index.md
  • mkdocs.yml

Documentos dependientes principales:

  • docs/governance/GOVERNANCE-CONTROL-TOWER.md
  • docs/governance/VALIDATION-STATE.md
  • docs/governance/REGRESSION-MATRIX.md
  • docs/governance/catalog/*.md
  • docs/governance/operations/*.md
  • docs/governance/knowledge/**/*.md
  • docs/architecture/*.md
  • docs/business/**/*.md
  • docs/tenants/**/*.md

Duplicaciones aparentes:

  • CODEX.md y REPO-OPERATING-CONTRACT.md comparten contrato operativo.
  • PROJECT-STATE.md, ROADMAP.md, GOVERNANCE-CONTROL-TOWER.md y algunos estados tenant repiten partes de estado y cierre.
  • Business Observer global y Business Observer APV repiten conceptos que deben distinguir Core vs Tenant.
  • Sources, mappings, authority SQL, data contracts y design docs se rozan en definiciones de campos, origen y destino.

Documentos potencialmente huerfanos:

  • No se detecto un huerfano bloqueante.
  • Si se detecto riesgo de descubribilidad: 133 Markdown bajo docs/ no aparecen directamente en mkdocs.yml.
  • Esta cifra no implica error: muchos documentos son evidencia, plantillas, catalogos atomicos o piezas referenciadas desde indices internos.
  • Riesgo real: que documentos importantes queden fuera de mkdocs.yml, README.md o INDEX.md.

Duplicidades y riesgos

Conceptos repetidos:

  • autoridad documental
  • fuente de verdad
  • estado global
  • proximo paso unico
  • contrato operativo
  • reglas de cierre
  • frontera Core vs Tenant
  • evidencia vs estimacion

Fuentes de estado multiples:

  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/governance/GOVERNANCE-CONTROL-TOWER.md
  • docs/governance/VALIDATION-STATE.md
  • project states por tenant
  • roadmaps por tenant

Riesgo de drift documental:

  • alto si se agregan blueprints sin declarar autoridad y frontera
  • medio si PROJECT-STATE y ROADMAP se actualizan sin criterio
  • medio si el portal omite documentos rectores nuevos
  • bajo si ACTIVE-CONTEXT.md sigue actuando como router operativo

Riesgo de sobredocumentacion:

  • alto si cada concepto menor genera un documento nuevo
  • alto si los blueprints copian contratos, mappings o DDL
  • medio si se agregan indices paralelos sin retirar responsabilidad de los indices existentes
  • bajo si la constitucion se mantiene corta y los blueprints se crean solo por dominio real

Madurez metodologica

Puntaje de 0 a 5:

Dimension Puntaje Evidencia
Vision 4 Roadmap futuro, Business Observer y arquitectura multi-tenant claros.
Gobernanza 4 Governance fuerte, aunque faltaba constitucion compacta.
Roadmap 4 Roadmap global y tenant extensos, con riesgo de crecer demasiado.
Arquitectura 4 Documentos rectores claros para multi-tenant, data y API.
Catalogo 4 Catalogos y fichas tecnicas amplios en governance.
Glosario 3 Glosarios locales existen, falta regla global de no redefinir.
Implementacion 3 Mucha base documental, pero blueprints aun no formalizados.
Evidencia 4 Inventarios, validaciones y estados certificados abundantes.

Conclusion

OpenClaw ya usa parcialmente:

  • Documentation First: si, de forma fuerte.
  • Governance Driven: si, especialmente en VPS, operaciones y validacion.
  • Blueprint Driven: parcialmente; existen documentos rectores, contratos, sources, mappings y design docs, pero no una capa blueprint formal.

Conviene formalizar OpenClaw Blueprint Governance Model.

La formalizacion debe ser liviana:

  • crear constitucion minima
  • declarar jerarquia documental
  • documentar la capa futura de blueprints
  • no crear blueprints funcionales todavia
  • no mover documentacion existente
  • no unificar PROJECT-STATE y ROADMAP
  • no reemplazar CODEX.md, ACTIVE-CONTEXT.md ni docs/governance/

No conviene tocar:

  • runtime
  • VPS
  • Docker
  • queries
  • SQL ejecutable
  • estructura historica de evidencias
  • nombres de documentos existentes
  • autoridad funcional actual del Business Observer APV