ontoref — About Jesús Pérez

Philosophy

A self-describing project protocol. A project declares its axioms, tensions, practices, state and gates as typed NCL — queryable to validate architectural decisions and audit coherence, the same way across software, infrastructure and personal domains. The protocol is specification and tooling; it is never a runtime dependency.

Built with

Nickel · Nushell · Rust

Features

Key ideas (5)

Three-layer NCL pattern: schemas → defaults → config.
Reflection modes: structured agent/developer workflows.
DAG topology for architectural decisions.
Gate membranes for controlled external signal entry.
Protocol — never a runtime dependency.

Why it matters

Substance and act, bound by the witness-seam: every architectural decision is queryable NCL, every tier-2 mutation deposits an Ed25519 witness in a replayable oplog DAG, and drift between intent and implementation is caught automatically.

No drift

The system gives itself away when it drifts: code, docs and even the marketing fail CI on the next commit, not the next audit — the positioning layer itself is drift-checked against ADR status.
Accredited knowledge

You act on accredited knowledge, not assumed or generated: verify any slice without loading the whole, and treat generated output — including an AI agent's — as unusable until it is signed.
Domain-transversal

The same substrate governs software, infrastructure, personal ontology, content and design — one typed graph across domains, not a vertical bound to one kind of data.
Graduated adoption

Enter with one NCL file and climb tiers only when it hurts; never a hostage to a runtime or a SaaS — tier choice is per-project, voluntary and indefinite.

The ladder

Between «I declare it» and «it can be checked» there are seven rungs. Each one presupposes the one below it, is checked by a machine only as far as its necessary conditions go, and names the question no check can answer. Each rung in detail →

1 · Reason for being

The reason for being lives somewhere that can be asked again, and answers with what the project is today without anyone rewriting it for the occasion.
2 · Reflection

What the project knows about itself gets executed — a mode, a step, a verifier — and leaves a trace of having run.
3 · Categories and relations

What is stated is in a closed vocabulary with declared relations, which is the precondition for a validator to exist at all.
4 · Territory and criterion

How far the governed reaches is declared, and so is what measures that it still does; the criterion refuses on a failing condition, and what must not be decided is held by reporting direction instead of imposing a winner.
5 · Accreditation

The terms are declared before and outside whoever executes, whoever executes emits signed evidence, and what is verified is that evidence and not their report — named responsibility, not a principle of authority.
6 · Observability

There is a question that returns the distance between what is declared and what is there, because observing is cheaper than remembering and remembering fails silently.
7 · Knowledge lineage

Where what the project knows came from is on record with an address, a quote and custody — including what was read and touched nothing, and what was believed inherited and was its own.

History

Started 2026

2026-09-02 Constellation layout, positioning framework and substrate foundations (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 Constellation-memory, viability and honest-limits arc (ADR-049…057).
2026-07-09 Licence travels with the distribution
2026-06-03 OCI distribution and installer — runnable image plus curl|sh (ADR-038).
2026-05-26 Verifiable substrate — witness, validators, operations layer; ontology/reflection duality (ADR-023/024/026/031).
2026-03-12 Genesis — standalone protocol project: three-layer NCL, ADR lifecycle, reflection modes, unified auth (ADR-001/005).

Graph

↗ Open the interactive graph

What it is

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…

Glossary

Disciplines (1)

Ondaod · onref-dao-discipline

Ontoref Dao Discipline. Before architectural analysis or ADR drafting, read the named tensions in core.ncl, identify which the question engages, and describe the synthesis state and direction of motion — do not collapse the Spiral by picki…

Concepts (30)

Spiral · spiral

Resolution mode of a Yin/Yang tension where neither pole wins and the system oscillates between them with synthesis emerging from the motion itself. In core.ncl, nodes carry `pole = 'Spiral` when they ARE the tension rather than a position w…
Synthesis · synthesis

Resolution of a Spiral tension by giving each pole its own plane of operation instead of choosing one. Both poles remain active, applied to different aspects. Synthesis is the productive answer to a Spiral; collapse is the regressive one.
PAP · project-architecture-principles

Project's Architecture Principles. The active set of invariants, patterns and rules that define how a specific project is built — drawn from its axioms, accepted ADRs and named practices. Saying something is anti-PAP means it is completely…
DAG-Formalized Knowledge · dag-formalized

Project axiom: all project knowledge — concepts, tensions, decisions, state — is formalized as directed acyclic graphs. Enables transversal queries, impact analysis and ecosystem-level visibility. The 'dao-formalized' spelling that occas…
ontoref · Ontoref

The protocol itself: a typed, queryable surface on which a project declares WHAT IT IS (ontology) and HOW IT ACTS (reflection), so a claim about the project can be contradicted by a machine and not only by a reader. Its dual layer is `on+re`…
Projection (constellation member) · projection

In the constellation member taxonomy (ADR-062), a member category: one source whose frontier lives INSIDE the build, never its own git repo. A Projection is materialised into each surface that needs it (e.g. assets, examples, docs), synced n…
Projection (positioning reveal)

In the reveal architecture (ADR-057), the act of PROJECTING the positioning graph (spine.ncl + generator) onto the outward site: doors generated from a structured contract, a drift fixed by re-running the projection, never by hand-editing th…
gov (the root, not one of its three words) · governance

`gov` is the id, the CLI alias and the host root of ontoref's self-domain (code/domains/gov/). It is the ROOT the three governance words share and abbreviates NONE of them — English has all three, with three referents, declared one per row…
Domain (repo_kind CLI extension) · cli-domain

A repo_kind-activated CLI extension under code/domains/{id}/: a project's repo_kind turns on its domain, giving project-type-aware commands (e.g. DD7pasos→knowledge-works, DevWorkspace→provisioning). ALL code/domains/* are domains. `sche…
Door (marketing funnel entry) · funnel-door

One of the outward funnel entries projected from spine.ncl (ADR-057/064): gov / infrastructure / authoring / personal. A door is an AUDIENCE-facing routing hook that carries a content `tag` (e.g. gov, knowledge-works) and routes to real cont…
Bond · bonding

A typed relation between projects (and their domains) within the ontoref framework — distinct from a `link`, which is a generic node reference (the `ln`/Link schema). A bond carries an AXIS: governance (the project is an ontoref-node in a…
Ontoref node · nodo-ontoref

A project seen along the GOVERNANCE axis of a bond: a governed member of a domain's graph. The governance axis is a DAG (acyclic, hierarchical): a domain (level N) governs its instances/implementations (level N+1) with Delegate / Override /…
Ontoref plane · plano-ontoref

The coexistence surface a project inhabits along the DEPENDENCY axis of a bond. Unlike the governance DAG, the dependency graph permits cycles: a `mutual` bond (DDD Partnership — "no deploy without service, no service without deploy") is a…
Bond axis · eje

The eje a bond runs along — one of two. GOVERNANCE: who governs whom, an acyclic DAG resolved with Delegate / Override / Compose. DEPENDENCY: who needs whom, a plane that permits cycles, typed with a DDD dependency-edge and optionally `mut…
Dependency edge · arista

The typed arista of a DEPENDENCY-axis bond, classified with a DDD Context-Map kind: CustomerSupplier, Partnership, OpenHostService, Conformist, SharedKernel, AnticorruptionLayer. DDD is borrowed ONLY here — as the dependency-edge type enum…
Linkage state · estado-de-vinculacion

The FSM state a bonded project occupies: None (not bonded), Linked (a dependency bond — inhabits a plane), Node (a governance bond — a governed node in a domain's DAG), or Managed (ontoref governs the project's development). Transitions…
Sensor · sensors

Feedback control in a coding-agent harness: the check that fires AFTER the model generates, correcting what a guide could not prevent. Böckeler splits sensors into COMPUTATIONAL (deterministic, cheap, milliseconds — linters, tests, struct…
Guide · guides

Feedforward control in a coding-agent harness: what steers the model BEFORE it writes — architecture docs, convention files, skills. In ontoref a guide is not a file the agent must remember to read: it is what the subject SERVES when queri…
Harnessability · harnessability

A property of a PROJECT, not of its harness: how much any harness can learn about the project BY ASKING, with nobody having explained it first. It is measured by what the project declares and serves, never by how well a particular harness ha…
Ambient affordances · affordance

Structural properties that make an environment legible and actionable without anyone giving instructions: you can see what can be done just by looking. Kept in English in Spanish prose — there is no settled Spanish form, and inventing one…
Hard / Soft severity · Hard

The typed severity of an ADR constraint. `'Hard` BINDS — a violation breaks. `'Soft` IS AUDITED — it is reported and does not block. Severity says how much the rule obliges; it does not say whether anyone checks it, and that gap is the w…
Consistency is not correctness · decidability is not adequacy

A passing check accredits CONSISTENCY — that everything it looked at agrees — and never CORRECTNESS, which is a claim about a domain the check was never handed. The formulation is Nicolas Figay's, from «The Other Ceiling»: a reasoner r…
warrant · warrant operacional

The evidence on whose authority something is admitted — a term into a vocabulary, a node into the graph, a result into the verifiable set. Borrowed from ANSI/NISO Z39.19, which admits a term on three distinct grounds that routinely conflic…
Rung · peldaño

One link of the ladder: a claim about what must hold for a project's reason for being to stay CHECKABLE rather than merely remembered. A rung carries the ontology nodes that already hold it, the verbs that answer it, the necessary conditions…
Cell · celula

A unit with a constitutional nucleus and an expression interface, which participates in operational processes and whose validity is determined by its real participation, not by its form. The nucleus is stateless and portable; memory, role an…
Tissue · tejido

The context that differentiates cells, holds their participation memory and specialises them. It is local and does not cross: the same cell is a sensor in one tissue and a policy in another, because role is an axis of expression the tissue a…
Membrane · membrana

A permeability boundary at any level: it decides what crosses and under what condition. Cell-scale projection of `gate` — same concept, different scale, and deliberately a different id rather than a redefinition. This term closes a gap tha…
Apoptosis

Programmed death: the deliberate collapse of a cell that enables reconstitution. Cell-scale projection of `pole-collapse` — a collapse chosen and recorded, as opposed to one suffered. A cell whose paid case no longer exists, or whose claim…
Cellular latency · latencia-celular

A held tension at cell scale: no tissue expresses the cell right now, its lineage is intact, and the criterion for reactivating it is written down. Cell-scale projection of `spiral` — the tension is sustained rather than resolved by deleti…
Epigenetics · epigenetica

The fast path: contextual modulation of how a cell is expressed, without touching its nucleus — without altering its constitution. It is the counterpart of the slow constitutional path, and the pair is the point — the two speeds are what…

Practices (4)

on+re · on+re

Shorthand for the Ontoref dual layer: ontology (`.ontoref/ontology/`: core.ncl, state.ncl, gate.ncl, manifest.ncl — what IS) + reflection (`.ontoref/reflection/`: modes, backlog, constraints, qa — what BECOMES). Both live under the singl…
Glossary Extension Pattern · glossary-extension

Three-level inheritance for vocabulary: a protocol seed at reflection/defaults/glossary.ncl shipped with ontoref; project terms appended in .ontoref/ontology/glossary.ncl::project_terms via d.seed_terms @ project_terms; optional domain split…
Encargo (work commission) · work-commission

Umbrella for the governance unit that constrains an agent by checking the deliverable against explicit terms instead of trusting the operator. An Encargo = one SOW (the terms) + its Work Orders (the executions). Two atomic rules make it a ha…
Making a difference · marcar-diferencia

The validity criterion for a cell: it is alive if and only if its verdict can alter at least one decision in at least one circuit. Cell-scale projection of adr-070 ("existing is not participating") and adr-072 (a check that could not look):…

Artifacts (10)

Gate · ontology-gate

Typed prerequisites and policies controlling FSM state transitions in a project. Lives at `.ontoref/ontology/gate.ncl`. Each dimension declares the conditions a transition must satisfy (catalysts present, blockers cleared); the reflection la…
onre · ontoref-cli

Shell alias for the `ontoref` CLI. Not a separate binary — invoked as `onre <subcommand>`, equivalent to `ontoref <subcommand>`. `onre` (on+re) replaced the former `ore` alias. Used in documentation and conversation as the operator-facing…
Verified witness · witness

A content-addressed, Ed25519-signed receipt of an act, deposited at the witness-as-axis seam. It proves *that* a check ran and what it returned — structure, never truthfulness (ADR-050). Necessary but not sufficient as a gate: a witness is…
Statement of Work (SOW) · sow

The terms layer of an Encargo: scope (minimal context + one-sentence objective), a falsifiable contract (a machine check, schema or constraint), and the validation mode ('Machine | 'Adversarial, signed or not). Owned by the human, outside th…
Work Order (WO) · ot

The execution layer of an Encargo, run under one SOW: disposable, contained, owned by the agent. Carries the deliverable, an observability envelope (workdir, Rust-style log level, JSONL output, start/end timestamps), the verified witness, an…
.domains-ontoref/ · domains-ontoref

The consumer-side container a bonded project carries: one subfolder per bonded domain (`.domains-ontoref/<domain>/`). Each subfolder holds a REQUIRED `bonds.ncl` (a BondSet) and an OPTIONAL implementation spine (federated `ontology/schemas/`…
Harness · harness

The wrapper that runs the model: context, tools, loop. An agent is model + harness. The harness steers with guides and corrects with sensors. Ontoref is NOT a harness and must never be described as one: it is what a harness QUERIES — the t…
Knowledge lineage · linaje-del-saber

The descent of what a project knows: which outside work a claim came from, reached by a stable address, quoted in bounded literal form with a locator, and backed by custody of the artefact it was read in. It is NOT the list of sources — so…
Nucleus · nucleo

The `.ncl` of a cell: claim, evaluation and interface, plus the identity and lineage that make it the same cell across tissues. It is constitutional and slow — changing it IS a mutation, and a mutation carries author, date and parent. It i…
Lineage · linaje

The derivation chain of nuclei: which cell a cell came from, who changed it, when, and what the diff was. Differentiation does not touch it; mutation extends it. Lineage is what makes a cell that has crossed between tissues auditable — wit…

Procedures (2)

adr? · adr-evaluation

Evaluation procedure invoked at the end of a session or feature. Five criteria must all hold to justify an ADR: (1) a meaningful alternative was consciously rejected; (2) lasting constraints for future contributors; (3) reversal needs coordi…
Differentiation · diferenciacion

Expressing a cell in a tissue without collapsing its definition: target, threshold, circuits and role are set here, and the nucleus is not touched. Cell-scale projection of `synthesis` — the cell keeps its general definition AND acquires a…

Antipatterns (2)

Yin/Yang Collapse · pole-collapse

Antipattern in which a Spiral tension is forcibly resolved by adopting one pole as 'the answer' and dropping the other. Usually appears as a flip: Yang → Yin (e.g. all-centralized to all-scripted) or vice versa, when the correct move is sy…
anti-PAP · antipap

Approach that violates the project's PAP outright. Not 'slightly off' or 'in tension with' — a proposal called anti-PAP is rejected at design time, before implementation.

About ontoref