ontoref — Acerca de Jesús Pérez

Filosofía

Un protocolo de proyecto autodescriptivo. Un proyecto declara sus axiomas, tensiones, prácticas, estado y gates como NCL tipado — consultable para validar decisiones arquitectónicas y auditar coherencia, del mismo modo en software, infraestructura y dominios personales. El protocolo es especificación y herramientas; nunca una dependencia en tiempo de ejecución.

Construido con

Nickel · Nushell · Rust

Características

Key ideas (5)

Patrón NCL de tres capas: schemas → defaults → config.
Modos de reflexión: flujos estructurados de agente/desarrollador.
Topología DAG para decisiones arquitectónicas.
Membranas de gate para entrada controlada de señales externas.
Protocolo — nunca una dependencia en tiempo de ejecución.

Por qué importa

Sustancia y acto, unidos por la costura-testigo: cada decisión arquitectónica es NCL consultable, cada mutación de tier-2 deposita un testigo Ed25519 en un DAG de oplog reproducible, y la deriva entre intención e implementación se detecta automáticamente.

Sin deriva

El sistema se delata cuando deriva: código, documentación e incluso el marketing fallan en CI en el siguiente commit, no en la siguiente auditoría — la propia capa de posicionamiento se verifica contra el estado de las ADR.
Conocimiento acreditado

Actúas sobre conocimiento acreditado, no asumido ni generado: verifica cualquier porción sin cargar el todo, y trata la salida generada — incluida la de un agente de IA — como inutilizable hasta que esté firmada.
Transversal a dominios

El mismo sustrato gobierna software, infraestructura, ontología personal, contenido y diseño — un grafo tipado a través de dominios, no un vertical atado a un solo tipo de dato.
Adopción graduada

Entra con un solo archivo NCL y sube de tier solo cuando duela; nunca rehén de un motor en tiempo de ejecución o un SaaS — la elección de tier es por proyecto, voluntaria e indefinida.

Historia

Desde 2026

2026-07-27 Layout de constelación, framework de posicionamiento y cimientos del sustrato (ADR-035/043/048).
2026-07-27 Arco de memoria de constelación, viabilidad y límites honestos (ADR-049…057).
2026-07-09 Proyección de docsite — mdBook generado desde la ontología (ADR-060).
2026-06-03 Distribución OCI e instalador — imagen ejecutable y curl|sh (ADR-038).
2026-05-26 Substrato verificable — testigo, validadores, capa de operaciones; dualidad ontología/reflexión (ADR-023/024/026/031).
2026-03-12 Génesis — proyecto-protocolo independiente: NCL de tres capas, ciclo de ADR, modos de reflexión, auth unificada (ADR-001/005).

Grafo

↗ Abrir el grafo interactivo

Qué es

Axioms (4)

Protocol, Not Runtime · Yang

Onref is a protocol specification and tooling layer. It is never a runtime dependency. Projects implement the protocol; onref provides the schemas and modules to do so.
Self-Describing · Yang

Onref describes itself using its own protocol. The .ontology/, adrs/, and reflection/ directories in this repository are onref consuming ontoref.
DAG-Formalized Knowledge · Yin

All project knowledge — concepts, tensions, decisions, state — is formalized as directed acyclic graphs. This enables transversal queries, impact analysis, and ecosystem-level visibility.
Sufficient Verification over Complete Knowledge · Spiral

Verification is always local and partial. Any actor — human or agent — can verify that a slice (an op, a node, a change) is coherent with what is declared WITHOUT possessing or loading global knowledge of the whole. The protocol will nev…

Tensions (3)

Formalization vs Adoption Friction · Spiral

Richer formalization produces better ecosystem visibility but increases the cost of adoption. The balance: schemas are optional layers, not mandatory gates.
Ontology vs Reflection · Spiral

Ontology captures what IS (invariants, structure, being). Reflection captures what BECOMES (operations, drift, memory). Both must coexist without one dominating. This tension is onref's core identity. It is held open architecturally — neve…
Openness vs Sustainability · Spiral

The protocol gives value away to maximize ecosystem reach — open schemas, voluntary-adoption, the personal-ontology audience, difusión as visibility — while the project that maintains it must capture enough value to sustain itself: dire…

Practices (7)

ADR Lifecycle · Yang

Architectural decisions follow: Proposed → Accepted → Superseded. Superseded ADRs retain constraints for historical reconstruction. Active Hard constraints drive the constraint set. Nodes declare which ADRs validate them via the adrs fie…
Reflection Modes · Yang

Operational procedures are first-class artifacts encoded as NCL DAG contracts. Modes declare actors, steps, dependencies, and error strategies — not prose. Forms (reflection/forms/) provide structured input schemas that feed into modes and…
Describe Query Layer · Yang

describe.nu aggregates all project sources and answers self-knowledge queries: what IS this, what can I DO, what can I NOT do, what tools exist, what is the impact of changing X. Renders Validated by section when a node declares adrs. descri…
Protocol Migration System · Yang

Progressive, ordered protocol migrations for consumer projects. Each migration is an NCL file in reflection/migrations/NNN-slug.ncl declaring id, slug, description, a typed check (FileExists | Grep | NuCmd), and instructions interpolated at…
Ontology Three-File Split · Yang

The .ontology/ directory separates three orthogonal concerns into three files. core.ncl captures what the project IS — invariant axioms and structural tensions; touching invariant=true nodes requires a new ADR. state.ncl captures where it…
Project Onboarding · Yang

Idempotent onboarding via `ontoref setup`. Creates .ontoref/project.ncl, .ontoref/config.ncl (with logo auto-detection in assets/), .ontology/ scaffold, adrs/, reflection/modes/, backlog.ncl, qa.ncl, git hooks, and registers in projects.ncl.…
Q&A Knowledge Store · Yin

Accumulated Q&A entries persisted as NCL — questions and answers captured during development sessions, AI interactions, and architectural reviews. Git-versioned, typed by QaEntry schema, queryable via MCP (ontoref_qa_list/add) and HTTP (/q…

Glosario

Disciplines (1)

Ondaod · onref-dao-discipline

Disciplina Dao de Ontoref. Antes de cualquier análisis arquitectónico o redacción de ADR, lee las tensiones nombradas en core.ncl, identifica cuáles activa la pregunta y describe el estado de síntesis y la dirección del movimiento —…

Concepts (19)

Espiral · spiral

Forma de resolución de una tensión Yin/Yang en la que ningún polo gana y el sistema oscila entre ellos, con la síntesis emergiendo del propio movimiento. En core.ncl los nodos llevan `pole = 'Spiral` cuando SON la tensión en lugar de un…
Síntesis · synthesis

Resolución de una tensión en Espiral asignando a cada polo su propio plano de operación en lugar de elegir uno. Ambos polos permanecen activos, aplicados a aspectos distintos. La síntesis es la respuesta productiva a una Espiral; el cola…
PAP · project-architecture-principles

Project's Architecture Principles (Principios de Arquitectura del Proyecto). Conjunto activo de invariantes, patrones y reglas que definen cómo se construye un proyecto concreto — derivado de sus axiomas, ADRs aceptados y prácticas nombr…
Conocimiento formalizado como DAG · dag-formalized

Axioma del proyecto: todo el conocimiento — conceptos, tensiones, decisiones, estado — se formaliza como grafos dirigidos acíclicos. Habilita consultas transversales, análisis de impacto y visibilidad a nivel de ecosistema. La grafía…
Projection (miembro de constelación) · projection

En la taxonomía de miembros de la constelación (ADR-062), una categoría de miembro: una sola fuente cuya frontera vive DENTRO del build, nunca su propio repo git. Un Projection se materializa en cada superficie que lo necesita (assets, ex…
Projection (revelado de posicionamiento)

En la arquitectura de revelado (ADR-057), el acto de PROYECTAR el grafo de posicionamiento (spine.ncl + generador) sobre el site externo: puertas generadas desde un contrato estructurado, una deriva se arregla re-ejecutando la proyección, n…
Dominio (extensión CLI por repo_kind) · cli-domain

Una extensión CLI activada por repo_kind bajo code/domains/{id}/: el repo_kind de un proyecto enciende su dominio, dando comandos conscientes del tipo de proyecto (p. ej. DD7pasos→knowledge-works, DevWorkspace→provisioning). TODOS los c…
Puerta (entrada de embudo) · funnel-door

Una de las entradas del embudo externo proyectadas desde spine.ncl (ADR-057/064): developer / infrastructure / authoring / personal. Una puerta es un gancho de enrutado orientado a AUDIENCIA que lleva un `tag` de contenido (p. ej. developer,…
Vínculo · bonding

Relación tipada entre proyectos (y sus dominios) dentro del marco ontoref — distinta de un `link`, que es una referencia genérica entre nodos (el esquema `ln`/Link). Un vínculo lleva un EJE: gobernanza (el proyecto es un nodo-ontoref en…
Nodo ontoref · nodo-ontoref

Un proyecto visto por el eje de GOBERNANZA de un vínculo: miembro gobernado del grafo de un dominio. El eje de gobernanza es un DAG (acíclico, jerárquico): un dominio (nivel N) gobierna sus instancias/implementaciones (nivel N+1) con sem�…
Plano ontoref · plano-ontoref

La superficie de coexistencia que un proyecto habita por el eje de DEPENDENCIA de un vínculo. A diferencia del DAG de gobernanza, el grafo de dependencia admite ciclos: un vínculo `mutual` (Partnership de DDD — "no hay deploy sin servici…
Eje del vínculo · eje

El eje por el que corre un vínculo — uno de dos. GOBERNANZA: quién gobierna a quién, un DAG acíclico resuelto con Delegate / Override / Compose. DEPENDENCIA: quién necesita a quién, un plano que admite ciclos, tipado con una arista d…
Arista de dependencia · arista

La arista tipada de un vínculo por el eje de DEPENDENCIA, clasificada con una clase del Context-Map de DDD: CustomerSupplier, Partnership, OpenHostService, Conformist, SharedKernel, AnticorruptionLayer. DDD se toma prestado SOLO aquí — c…
Estado de vinculación · estado-de-vinculacion

El estado que ocupa un proyecto vinculado en la máquina de estados: None (sin vínculo), Linked (vínculo de dependencia — habita un plano), Node (vínculo de gobernanza — nodo gobernado en el DAG de un dominio) o Managed (ontoref gobie…
Sensor · sensors

Control por realimentación en un arnés de agentes: la comprobación que se dispara DESPUÉS de que el modelo genere, y corrige lo que una guía no pudo prevenir. Böckeler divide los sensores en COMPUTACIONALES (deterministas, baratos, mil…
Guía · guides

Control anticipativo (feedforward) en un arnés de agentes: lo que orienta al modelo ANTES de que escriba — documentación de arquitectura, ficheros de convenciones, skills. En ontoref una guía no es un fichero que el agente deba acordars…
Arnesabilidad · harnessability

Propiedad de un PROYECTO, no de su arnés: cuánto puede un arnés cualquiera averiguar del proyecto PREGUNTANDO, sin que nadie se lo haya explicado antes. Se mide por lo que el proyecto declara y sirve, nunca por lo bien configurado que est…
Ambient affordances · affordance

Propiedades estructurales que hacen un entorno legible y accionable sin que nadie dé instrucciones: se ve qué se puede hacer con solo mirar. Se deja en inglés en prosa española — no hay forma asentada, e inventar una haría crecer un s…
Severidad Hard / Soft · Hard

La severidad tipada de una restricción de ADR. `'Hard` VINCULA — una violación rompe. `'Soft` SE AUDITA — se reporta y no bloquea. La severidad dice cuánto obliga la regla; no dice si alguien la comprueba, y ese hueco es la cifra de 9…

Practices (3)

on+re · on+re

Abreviatura de la doble capa de Ontoref: ontología (`.ontology/`: core.ncl, state.ncl, gate.ncl, manifest.ncl — lo que ES) + reflexión (`reflection/`: modos, cartera de pendientes, restricciones, qa — lo que DEVIENE). Toda instancia in…
Patrón de Extensión del Glosario · glossary-extension

Herencia en tres niveles para vocabulario: una semilla de protocolo en `reflection/defaults/glossary.ncl` que ontoref distribuye; términos de proyecto añadidos en `.ontology/glossary.ncl::project_terms` vía `d.seed_terms @ project_terms`;…
Encargo · work-commission

Paraguas de la unidad de gobierno que constriñe a un agente comprobando el entregable contra términos explícitos en vez de fiarse del operario. Un Encargo = un Pliego (los términos) + sus Órdenes de Trabajo (las ejecuciones). Dos reglas…

Artifacts (7)

Gate · ontology-gate

Prerrequisitos tipados y políticas que controlan las transiciones de estado de la máquina de estados de un proyecto. Vive en `.ontology/gate.ncl`. Cada dimensión declara las condiciones que una transición debe satisfacer (catalizadores p…
onre · ontoref-cli

Alias de shell para el CLI `ontoref`. No es un binario aparte — se invoca como `onre <subcomando>`, equivalente a `ontoref <subcomando>`. `onre` (on+re) sustituyó al antiguo alias `ore`. Se usa en documentación y conversación como nombr…
Testigo verificado · witness

Acta de un acto, direccionada por contenido y firmada con Ed25519, depositada en la costura witness-as-axis. Demuestra *que* una comprobación se ejecutó y qué devolvió — estructura, nunca veracidad (ADR-050). Necesaria pero no suficien…
Pliego · sow

La capa de términos de un Encargo: alcance (contexto mínimo + objetivo en una frase), un contrato refutable (una comprobación de máquina, esquema o restricción) y el modo de validación ('Maquina | 'Adversario, firmado o no). Lo posee l…
Orden de Trabajo (OT) · ot

La capa de ejecución de un Encargo, ejecutada bajo un Pliego: prescindible, acotada, propiedad del agente. Lleva el entregable, una envoltura de observabilidad (directorio de trabajo, nivel de registro al estilo Rust, salida en JSONL, marca…
.domains-ontoref/ · domains-ontoref

El contenedor del lado consumidor que lleva un proyecto vinculado: una subcarpeta por dominio vinculado (`.domains-ontoref/<dominio>/`). Cada subcarpeta contiene un `bonds.ncl` OBLIGATORIO (un BondSet) y una columna de implementación OPCION…
Arnés · harness

El envoltorio que ejecuta al modelo: contexto, herramientas, bucle. Un agente es modelo + arnés. El arnés dirige con guías y corrige con sensores. Ontoref NO es un arnés y nunca debe describirse como tal: es lo que un arnés CONSULTA —…

Procedures (1)

adr? · adr-evaluation

Procedimiento de evaluación que se invoca al final de una sesión o feature. Los cinco criterios deben cumplirse para justificar un ADR: (1) se rechazó conscientemente una alternativa significativa; (2) deja restricciones duraderas para fu…

Antipatterns (2)

Colapso Yin/Yang · pole-collapse

Antipatrón consistente en resolver forzosamente una tensión en Espiral adoptando un polo como 'la respuesta' y descartando el otro. Suele manifestarse como un flip: Yang → Yin (p. ej. todo-centralizado a todo-scripted) o viceversa, cuand…
anti-PAP · antipap

Enfoque que viola frontalmente el PAP del proyecto. No es 'ligeramente desviado' ni 'en tensión con' — una propuesta calificada como anti-PAP se rechaza en diseño, antes de implementar.

Acerca de ontoref