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.

History

Started 2026

2026-07-27 Constellation layout, positioning framework and substrate foundations (ADR-035/043/048).
2026-07-27 Constellation-memory, viability and honest-limits arc (ADR-049…057).
2026-07-09 Docsite projection — mdBook generated from the ontology (ADR-060).
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 .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…

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 (19)

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…
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…
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): developer / infrastructure / authoring / personal. A door is an AUDIENCE-facing routing hook that carries a content `tag` (e.g. developer, knowledge-works) and routes…
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…

Practices (3)

on+re · on+re

Shorthand for the Ontoref dual layer: ontology (`.ontology/`: core.ncl, state.ncl, gate.ncl, manifest.ncl — what IS) + reflection (`reflection/`: modes, backlog, constraints, qa — what BECOMES). Every onboarded project instance carries b…
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 .ontology/glossary.ncl::project_terms via d.seed_terms @ project_terms; optional domain splits in .on…
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…

Artifacts (7)

Gate · ontology-gate

Typed prerequisites and policies controlling FSM state transitions in a project. Lives at `.ontology/gate.ncl`. Each dimension declares the conditions a transition must satisfy (catalysts present, blockers cleared); the reflection layer eval…
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…

Procedures (1)

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…

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