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 domains 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 domains

El mismo sustrato gobierna software, infraestructura, ontología personal, contenido y diseño — un grafo tipado a través de domains, 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.

La escalera

Entre «lo declaro» y «se puede comprobar» hay siete peldaños. Cada uno presupone el anterior, una máquina lo comprueba sólo hasta donde llegan sus condiciones necesarias, y nombra la pregunta que ninguna comprobación puede contestar. Cada peldaño en detalle →

1 · Razón de ser

La razón de ser vive en un sitio al que se le puede volver a preguntar, y responde con lo que el proyecto es hoy sin que nadie la reescriba para la ocasión.
2 · Reflexión

Lo que el proyecto sabe de sí mismo se ejecuta —un modo, un paso, un verificador— y deja rastro de haberse ejecutado.
3 · Categorías y relaciones

Lo dicho está en un vocabulario cerrado y con relaciones declaradas, que es la condición de posibilidad de que exista un validador.
4 · Territorio y criterio

Está declarado hasta dónde llega lo gobernado y con qué se mide que lo sigue estando; el criterio rechaza sobre una condición que falla, y lo que no debe decidirse se sostiene reportando dirección en vez de imponer un vencedor.
5 · Acreditación

Los términos se declaran antes y fuera de quien ejecuta, quien ejecuta emite evidencia firmada, y lo que se verifica es esa evidencia y no su informe — responsabilidad con nombre, no principio de autoridad.
6 · Observabilidad

Existe una pregunta que devuelve la distancia entre lo declarado y lo que hay, porque observar sale más barato que recordar y recordar falla en silencio.
7 · Linaje del saber

De dónde viene lo que el proyecto sabe está registrado con dirección, cita y custodia — incluido lo que se leyó y no tocaba nada, y lo que se creyó heredar y era propio.

Historia

Desde 2026

2026-09-02 Layout de constelación, framework de posicionamiento y cimientos del sustrato (ADR-035/043/048).
2026-09-02 Release criteria derive from the declared relation, not from the diff (ADR-082, accepted)
2026-08-26 One storage substrate, and it is embedded (ADR-099, accepted)
2026-08-17 Arco de memoria de constelación, viabilidad y límites honestos (ADR-049…057).
2026-07-09 Licence travels with the distribution
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 .ontoref/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 .ontoref/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 w…
Project Onboarding · Yang

Idempotent onboarding via `ontoref setup`. Creates .ontoref/project.ncl, .ontoref/config.ncl (with logo auto-detection in assets/), .ontoref/ontology/ scaffold, adrs/, reflection/modes/, backlog.ncl, qa.ncl, git hooks, and registers in proje…
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 (30)

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…
ontoref · Ontoref

El protocolo en sí: una superficie tipada y consultable en la que un proyecto declara LO QUE ES (ontología) y CÓMO ACTÚA (reflexión), de modo que una afirmación sobre el proyecto pueda ser contradicha por una máquina y no sólo por un…
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…
gov (la raíz, no una de sus tres palabras) · governance

`gov` es el id, el alias de CLI y la raíz de host del dominio-de-sí de ontoref (code/domains/gov/). Es la RAÍZ que comparten las tres palabras de gobierno y no abrevia NINGUNA — el inglés tiene las tres, con tres referentes, declarados…
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): gov / infrastructure / authoring / personal. Una puerta es un gancho de enrutado orientado a AUDIENCIA que lleva un `tag` de contenido (p. ej. gov, knowledge-w…
Vínculo · bonding

Relación tipada entre proyectos (y sus domains) 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…
Consistencia no es corrección · decidability is not adequacy

Un check que pasa acredita CONSISTENCIA — que todo lo que miró concuerda — y nunca CORRECCIÓN, que es una afirmación sobre un dominio que al check nadie le dio. La formulación es de Nicolas Figay, en «The Other Ceiling»: un razonad…
warrant · warrant operacional

La evidencia con cuya autoridad algo se admite: un término en un vocabulario, un nodo en el grafo, un resultado en el conjunto verificable. Tomado de ANSI/NISO Z39.19, que admite un término por tres fundamentos distintos que entran en conf…
Peldaño · peldaño

Un eslabón de la escalera: una afirmación sobre lo que ha de sostenerse para que la razón de ser de un proyecto siga siendo COMPROBABLE y no solo recordada. Un peldaño lleva los nodos de la ontología que ya lo cargan, los verbos que lo…
Célula · celula

Unidad con un núcleo constitucional y una interfaz de expresión, que participa en procesos operativos y cuya validez la determina su participación real, no su forma. El núcleo no tiene estado y es portable; la memoria, el rol y la cadenc…
Tejido · tejido

El contexto que diferencia células, sostiene su memoria de participación y las especializa. Es local y no cruza: la misma célula es sensor en un tejido y política en otro, porque el rol es un eje de expresión que asigna el tejido, no un…
Membrana · membrana

Frontera de permeabilidad en cualquier nivel: decide qué cruza y bajo qué condición. Proyección a escala celular de `gate` — mismo concepto, otra escala, y deliberadamente otro id en lugar de una redefinición. Este término cierra un…
Apoptosis

Muerte programada: el colapso deliberado de una célula que habilita la reconstitución. Proyección a escala celular de `pole-collapse` — un colapso elegido y registrado, frente a uno padecido. Una célula cuyo caso pagado ya no existe, o…
Latencia celular · latencia-celular

Tensión sostenida a escala celular: ningún tejido expresa ahora mismo la célula, su linaje está intacto y el criterio para reactivarla está escrito. Proyección a escala celular de `spiral` — la tensión se sostiene en vez de resolver…
Epigenética · epigenetica

La vía rápida: modulación contextual de cómo se expresa una célula, sin tocar su núcleo — sin alterar su constitución. Es la contraparte de la vía constitucional lenta, y el par es lo importante — las dos velocidades son lo que p…

Practices (4)

on+re · on+re

Abreviatura de la doble capa de Ontoref: ontología (`.ontoref/ontology/`: core.ncl, state.ncl, gate.ncl, manifest.ncl — lo que ES) + reflexión (`.ontoref/reflection/`: modos, cartera de pendientes, restricciones, qa — lo que DEVIENE).…
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 `.ontoref/ontology/glossary.ncl::project_terms` vía `d.seed_terms @ project…
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…
Marcar diferencia · marcar-diferencia

El criterio de validez de una célula: está viva si y solo si su veredicto puede alterar al menos una decisión en al menos un circuito. Proyección a escala celular de adr-070 («existir no es participar») y adr-072 (una comprobación que…

Artifacts (10)

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 `.ontoref/ontology/gate.ncl`. Cada dimensión declara las condiciones que una transición debe satisfacer (cataliz…
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 —…
Linaje del saber · linaje-del-saber

La descendencia de lo que un proyecto sabe: de qué obra externa viene una afirmación, alcanzada por una dirección estable, citada literal y acotada con su localizador, y respaldada por la custodia del artefacto en que se leyó. NO es la l…
Núcleo · nucleo

El `.ncl` de una célula: afirmación, evaluación e interfaz, más la identidad y el linaje que la hacen ser la misma célula en tejidos distintos. Es constitucional y lento — cambiarlo ES una mutación, y una mutación lleva autor, fecha…
Linaje · linaje

La cadena de derivación de los núcleos: de qué célula viene una célula, quién la cambió, cuándo y cuál fue el diff. La diferenciación no lo toca; la mutación lo extiende. El linaje es lo que hace auditable una célula que ha cruza…

Procedures (2)

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…
Diferenciación · diferenciacion

Expresar una célula en un tejido sin colapsar su definición: aquí se fijan diana, umbral, circuitos y rol, y el núcleo no se toca. Proyección a escala celular de `synthesis` — la célula conserva su definición general Y adquiere una…

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