Document Hierarchy¶

Fecha: 2026-06-10

Estado: JERARQUIA RECOMENDADA LIVIANA

portal_visible = yes

Objetivo¶

Ordenar la documentacion de OpenClaw por niveles de autoridad para evitar redefiniciones, drift y sobredocumentacion.

Esta jerarquia no mueve archivos, no renombra documentos y no invalida la documentacion existente.

Regla general de visibilidad en Knowledge Portal¶

Todo documento rector, blueprint, contrato, diseno estable o evidencia relevante debe evaluar explicitamente si debe aparecer en el OpenClaw Knowledge Portal.

La evaluacion debe quedar declarada en el documento, en su README local, en la navegacion del portal o en el documento de governance que lo clasifica.

Clasificacion obligatoria:

portal_visible = yes: debe ser visible en el portal porque es autoridad, guia estable, blueprint principal, contrato o evidencia relevante para decision humana.
portal_visible = no: no debe ser visible porque es transitorio, redundante, local a una tarea menor o no aporta lectura estable.
portal_visible = internal_only: no debe publicarse en el portal porque contiene detalle interno, operativo, sensible, de seguridad, credenciales, runtime o informacion que no corresponde exponer navegablemente.
portal_visible = technical_reference: puede aparecer como referencia tecnica o soporte contextual, pero no debe promocionarse como documento rector ni lectura principal.
portal_visible = pending_review: la visibilidad esta pendiente de decision humana o revision de contenido; no debe tratarse como autoridad publicada hasta cerrarse el criterio.

Ejemplos rectores:

Project Constitution: portal_visible = yes
Document Hierarchy: portal_visible = yes
OpenClaw Blueprint Governance Model: portal_visible = yes
Blueprint Authoring Standard: portal_visible = yes
Business Observer Blueprints: portal_visible = yes
Data Contracts: portal_visible = yes
Source Authority SQL: portal_visible = technical_reference o portal_visible = internal_only, segun sensibilidad y utilidad de soporte
Change Packets: portal_visible = pending_review o portal_visible = internal_only, segun estado y contenido
documentos de runtime, seguridad, credenciales o detalles operativos sensibles: portal_visible = internal_only

Nivel 1 - Project Constitution¶

Documento recomendado:

docs/governance/PROJECT-CONSTITUTION.md

Estado: creado

Funcion:

declarar mision, principios y fuente de verdad documental
fijar la regla de no duplicar definiciones
ordenar la relacion ChatGPT / Codex

No debe contener:

roadmap
estado historico
evidencia extensa
diseno tecnico
reglas tenant detalladas

Nivel 2 - CODEX.md / ACTIVE-CONTEXT.md¶

Documentos existentes:

CODEX.md
docs/governance/ACTIVE-CONTEXT.md

Estado: existente

Funcion:

CODEX.md: contrato operativo raiz para trabajar con Codex
ACTIVE-CONTEXT.md: router operativo corto por modo

Regla:

no duplicar el contrato operativo en blueprints ni docs de diseno

Nivel 3 - Governance / Control Tower / Validation¶

Documentos existentes:

docs/governance/README.md
docs/governance/INDEX.md
docs/governance/GOVERNANCE-CONTROL-TOWER.md
docs/governance/VALIDATION-STATE.md
docs/governance/REGRESSION-MATRIX.md
docs/governance/CHANGE-GATES.md
docs/governance/catalog/*.md
docs/governance/documentation/BLUEPRINT-AUTHORING-STANDARD.md

Estado: existente

Funcion:

gobernar reglas, operaciones, servicios, catalogos, validacion, seguridad y evidencia de cierre

Regla:

cualquier cambio de regla o criterio de cierre debe enlazar con governance

Nivel 4 - Roadmap / Project State¶

Documentos existentes:

docs/ROADMAP.md
docs/PROJECT-STATE.md
roadmaps y project states por tenant cuando corresponda

Estado: existente

Funcion:

ROADMAP.md: secuencia historica y futura de etapas
PROJECT-STATE.md: estado certificado, decisiones y evidencia sintetica

Regla:

actualizar solo si cambia estado, decision, cierre, roadmap, pendiente o proximo paso unico recomendado

Nivel 5 - Blueprints¶

Carpeta activa documentada:

docs/tenants/alpuntodeventa/business-observer/blueprints/

Blueprints vigentes:

docs/tenants/alpuntodeventa/business-observer/blueprints/CUSTOMER-BLUEPRINT.md
docs/tenants/alpuntodeventa/business-observer/blueprints/PRODUCT-BLUEPRINT.md
docs/tenants/alpuntodeventa/business-observer/blueprints/SALES-BLUEPRINT.md
docs/tenants/alpuntodeventa/business-observer/blueprints/OWNERSHIP-BLUEPRINT.md
docs/tenants/alpuntodeventa/business-observer/blueprints/TERRITORY-BLUEPRINT.md

Estado: activa con blueprints funcionales principales

Funcion:

definir dominios funcionales estables antes de contrato, mapping, design o implementacion

Regla:

los blueprints nuevos o revisados deben seguir docs/governance/documentation/BLUEPRINT-AUTHORING-STANDARD.md
se deben crear solo cuando exista una necesidad funcional aprobada y una frontera clara
no crear blueprints decorativos ni subtareas disfrazadas de dominio

Nivel 6 - Contracts / Sources / Mappings¶

Documentos existentes o parcialmente existentes:

BUSINESS-OBSERVER-DATA-CONTRACT-001.md
sources/*.md
mappings/*.md
source-authority/*.md
SOURCE-INVENTORY-RESULTS-*.md

Estado: existente parcial

Funcion:

documentar fuente, autoridad, origen-destino, contrato funcional de datos y evidencia de inventario

Regla:

no copiar definiciones de contrato dentro de blueprints
no convertir source authority en blueprint

Nivel 7 - Design / DDL / Implementation¶

Documentos existentes o parcialmente existentes:

design/*.md
design/sql/*.sql
documentos de arquitectura en docs/architecture/

Estado: existente parcial

Funcion:

bajar decisiones a diseno tecnico, DDL documental, migraciones futuras o implementacion aprobada

Regla:

un blueprint no autoriza runtime
un DDL documental no implica ejecucion
toda implementacion real exige aprobacion explicita y evidencia

Nivel 8 - Evidence / Inventory Results / Change Packets¶

Documentos existentes:

SOURCE-INVENTORY-RESULTS-*.md
docs/governance/change-packets/*.md
docs/governance/audits/*.md
reportes de validacion y operaciones

Estado: existente

Funcion:

preservar evidencia, inventarios, decisiones de cambio y pruebas

Regla:

la evidencia no redefine el modelo
la evidencia respalda o bloquea decisiones

Niveles que faltaban¶

Nivel 1: Project Constitution explicita.
Nivel 5: carpeta, regla y blueprints funcionales principales.
Documento puente: modelo liviano de Blueprint Governance.
Estandar de autoria: BLUEPRINT-AUTHORING-STANDARD.md.

Niveles que no deben crearse todavia¶

Blueprints funcionales concretos sin necesidad aprobada.
Blueprints decorativos que dupliquen sources, mappings, contracts, design o evidence.
Master Index global nuevo si mkdocs.yml, README.md e INDEX.md bastan.
Glosario global si las definiciones locales siguen claras.
Carpetas paralelas de governance fuera de docs/governance/.

Como evitar redefiniciones¶

Antes de escribir una definicion, buscar si ya existe autoridad.
Si existe autoridad, enlazarla y no copiarla.
Si una definicion pertenece a Core, no guardarla como regla tenant.
Si una definicion pertenece a APV, no elevarla al Core sin decision.
Si algo es source, mapping, contract, design o evidencia, no llamarlo blueprint.
Si el documento cambia estado o roadmap, actualizar solo los puntos afectados.