Saltar a contenido

OpenClaw Blueprint Governance Model

Fecha: 2026-06-10

Estado: PROPUESTA FORMAL LIVIANA

Scope: governance documental

portal_visible = yes

Objetivo

Definir una metodologia documental liviana para que OpenClaw pueda evolucionar desde vision y governance hacia dominios funcionales implementables sin perder trazabilidad, sin duplicar definiciones y sin convertir la documentacion en burocracia.

El modelo ordena donde vive cada tipo de decision:

  • constitucion del proyecto
  • contrato operativo
  • contexto activo
  • governance y validacion
  • estado y roadmap
  • estandar de autoria de blueprints
  • blueprints funcionales
  • contratos, sources y mappings
  • design, DDL documental e implementacion futura
  • evidencia, inventarios y change packets

Principios

  • Documentar antes de implementar.
  • Una definicion oficial debe tener una sola autoridad.
  • Los blueprints explican el dominio, no reemplazan contratos ni DDL.
  • La evidencia pesa mas que la intuicion cuando hay decision tecnica o funcional.
  • La gobernanza debe reducir ambiguedad, no crear friccion innecesaria.
  • Cada capa documental debe enlazar hacia su autoridad superior.
  • Ningun documento nuevo debe redefinir algo que ya tiene fuente de verdad.
  • El runtime se toca solo con aprobacion explicita.
  • Los tenants pueden tener reglas propias sin contaminar el Core.
  • Todo avance relevante debe ser navegable desde el portal o desde un indice local claro.

Beneficios

  • Reduce drift entre vision, roadmap, estado, arquitectura y evidencia.
  • Hace mas claro que documento debe leer Codex antes de actuar.
  • Separa decision humana, governance, diseno y ejecucion.
  • Permite crear blueprints por dominio sin abrir runtime.
  • Protege a PROJECT-STATE.md y ROADMAP.md de convertirse en indice unico de todo.
  • Mantiene Business Observer APV alineado con Core vs Tenant.
  • Facilita auditorias futuras y revisiones humanas.

Riesgos

  • Crear documentos que nadie usa.
  • Duplicar definiciones entre blueprint, contract, mapping y design.
  • Convertir cada idea en un blueprint prematuro.
  • Usar blueprints como autorizacion implicita para construir runtime.
  • Agregar indices paralelos que compitan con mkdocs.yml y docs/governance/INDEX.md.
  • Mezclar reglas tenant APV con patrones reutilizables de OpenClaw.

Como evitar burocracia

  • Crear un blueprint solo cuando exista un dominio funcional real.
  • Mantener cada blueprint centrado en decisiones, vocabulario y fronteras.
  • Enlazar contratos, sources, mappings y design docs en vez de copiarlos.
  • Usar ACTIVE-CONTEXT.md como router operativo antes de abrir documentos grandes.
  • Actualizar PROJECT-STATE.md y ROADMAP.md solo cuando cambie estado, decision, cierre, roadmap o proximo paso.
  • No crear comites, formularios ni aprobaciones documentales nuevas salvo que reduzcan riesgo real.

Como evitar sobredocumentacion

  • No crear blueprints de subtareas.
  • No duplicar glosarios si ya existe una definicion oficial.
  • No copiar DDL, SQL, mappings ni contratos dentro del blueprint.
  • No transformar evidencia historica en documentos rectores.
  • No crear un nuevo indice global si mkdocs.yml, README.md o INDEX.md ya resuelven la navegacion.
  • Declarar pendiente o pendiente de validar antes que completar huecos con supuestos.

Impacto esperado a 1 anio

  • Menos confusion sobre donde vive cada decision.
  • Business Observer APV puede crecer por dominios sin mezclar source, contrato, design y evidencia.
  • Codex consume menos contexto porque la jerarquia indica que leer primero.
  • El portal conserva navegacion clara aunque aumente el volumen documental.
  • Los blueprints creados deberian ser pocos, estables y funcionales.

Impacto esperado a 3 anios

  • OpenClaw puede sostener varios tenants sin mezclar reglas locales.
  • Los dominios centrales tendran blueprint, contratos, mappings, design y evidencia trazables.
  • La metodologia puede servir como base para auditorias internas, onboarding y decision asistida por IA.
  • El repo puede crecer sin depender de memoria humana para ubicar autoridades.
  • La documentacion queda preparada para una futura Business Knowledge Platform sin imponerla ahora.

Relacion con CODEX.md

CODEX.md sigue siendo el contrato operativo raiz para trabajar con Codex.

El Blueprint Governance Model no lo reemplaza. Lo complementa con una regla de arquitectura documental: antes de crear implementacion, ubicar el tipo de documento correcto y no duplicar autoridad.

Relacion con ACTIVE-CONTEXT.md

ACTIVE-CONTEXT.md sigue siendo el router operativo corto.

Este modelo debe consultarse cuando la tarea sea GOVERNANCE, INVENTORY o DESIGN y afecte jerarquia documental, blueprints, fuentes de verdad o fronteras entre documentos.

Relacion con Governance

docs/governance/ sigue siendo la autoridad viva para reglas, control tower, validacion, operaciones, catalogos, servicios, runbooks y seguridad.

Este modelo vive dentro de governance porque define como ordenar la documentacion sin tocar runtime.

Relacion con Knowledge Portal

La metodologia documental debe evaluar la visibilidad de cada documento importante en el OpenClaw Knowledge Portal.

La fuente de criterio es Document Hierarchy:

  • documentos rectores, blueprints principales, contratos y disenos estables: portal_visible = yes
  • referencias tecnicas utiles, como SQL de autoridad o SQL documental: portal_visible = technical_reference o portal_visible = internal_only
  • change packets o evidencia en revision: portal_visible = pending_review o portal_visible = internal_only
  • runtime, seguridad, credenciales o detalle operativo sensible: portal_visible = internal_only

Un documento visible debe estar referenciado por mkdocs.yml, por un README local navegable o por un indice de governance. Un documento no visible debe conservar igualmente su autoridad en Git cuando corresponda.

Relacion con PROJECT-STATE / ROADMAP

PROJECT-STATE.md conserva el estado global certificado.

ROADMAP.md conserva la secuencia historica y futura de etapas.

Este modelo no convierte estado o roadmap en fuente unica de definiciones. Solo indica cuando deben actualizarse: si cambia estado, decision, cierre, roadmap o proximo paso unico recomendado.

Relacion con Blueprint Authoring Standard

BLUEPRINT-AUTHORING-STANDARD.md fija las reglas de autoria para crear o revisar blueprints funcionales.

Este modelo explica por que existe la capa Blueprint dentro de la jerarquia documental. El estandar define como escribir cada blueprint sin duplicar sources, mappings, contracts, design, DDL, implementation ni evidence.

Relacion con Business Observer

El Business Observer APV ya tiene autoridad funcional en BUSINESS-OBSERVER-GOVERNANCE-MODEL.md.

Los blueprints del Business Observer APV deben respetar esa autoridad:

  • no redefinir que es el observer
  • no duplicar UC existentes
  • no mezclar Core y Tenant
  • no copiar sources, mappings, contracts ni design docs
  • explicar dominio, preguntas, fronteras, vocabulario y decisiones funcionales
  • usar el Blueprint Authoring Standard como estructura minima de autoria

Criterio de adopcion

La metodologia queda adoptada cuando:

  • existe PROJECT-CONSTITUTION.md
  • existe DOCUMENT-HIERARCHY.md
  • existe BLUEPRINT-AUTHORING-STANDARD.md
  • existe una carpeta de blueprints documentada
  • los nuevos documentos importantes evaluan portal_visible
  • los documentos con portal_visible = yes aparecen en governance, portal o indice local navegable
  • los blueprints funcionales se crean solo con necesidad aprobada y frontera clara
  • no se toco runtime, VPS, Docker, queries ni codigo