5.0 KiB
ontoref is a protocol specification and tooling layer for structured self-knowledge in software projects. It provides schemas, Nushell automation, and Rust crates so that projects can describe what they are, record architectural decisions, track operational state, and execute formalized procedures — all as typed, queryable artifacts.
Axioms
| Axiom | Meaning |
|---|---|
| Protocol, Not Runtime | Never a runtime dependency. Projects adopt the protocol; ontoref provides the schemas and modules to do so. |
| Self-Describing | Consumes its own protocol: .ontology/, adrs/, reflection/ in this repo ARE ontoref running against itself. |
| No Enforcement | ontoref defines contracts. There is no enforcement mechanism. Coherence is voluntary and emerges from justified adoption. |
| DAG-Formalized Knowledge | Concepts, tensions, decisions, state — encoded as DAGs. Enables transversal queries and impact analysis. |
Layers
ontology/ Protocol specification — Nickel schemas for nodes, edges, ADRs, state, gates
adrs/ Architecture Decision Records — typed NCL with constraints and ontology checks
reflection/ Operational tooling — Nushell modules, DAG modes, forms, and schemas
crates/ Rust implementation — typed struct loaders and mode executors
.ontology/ Self-description — ontoref's own ontology, state, gate, and manifest
Crates
| Crate | Purpose |
|---|---|
ontoref-ontology |
Load .ontology/*.ncl as typed Rust structs. Zero stratumiops deps — minimal adoption surface. |
ontoref-reflection |
Load, validate, and execute Reflection modes as NCL DAG contracts against project state. |
ontoref-daemon |
NCL export cache, file watcher, actor registry, HTTP API, MCP server, Q&A store, quick-actions, passive drift observation. |
ontoref-daemon caches nickel export results (keyed by path + mtime), reducing full sync
scans from ~2m42s to <30s. The daemon is always optional — every module falls back to direct
subprocess when unavailable.
Daemon Capabilities
Q&A Knowledge Store — accumulated Q&A entries persist to reflection/qa.ncl (typed NCL,
git-versioned). Not localStorage. Any actor — developer, agent, CI — reads the same store.
MCP Server — exposes 8+ tools over stdio and streamable-HTTP for AI agent integration:
| Tool | What it does |
|---|---|
ontoref_qa_list |
List Q&A entries with optional filter |
ontoref_qa_add |
Append a new Q&A entry to reflection/qa.ncl |
ontoref_action_list |
List all quick actions from .ontoref/config.ncl |
ontoref_action_add |
Create a reflection mode + register it as a quick action |
ontoref_backlog_list |
List backlog items |
ontoref_backlog_add |
Add a backlog item |
ontoref_describe |
Describe project ontology and constraints |
ontoref_sync_scan |
Scan for ontology drift |
Passive Drift Observation — background file watcher that detects divergence between Yang
code artifacts and Yin ontology. Watches crates/, .ontology/, adrs/, reflection/modes/.
After a 15s debounce runs sync scan + sync diff; emits an ontology_drift notification when
MISSING/STALE/DRIFT/BROKEN items are found. Never applies changes — apply is always deliberate.
Quick Actions — runnable shortcuts over reflection modes, configured as quick_actions in
.ontoref/config.ncl. Accessible from HTTP (/actions), CLI (./ontoref), and MCP
(ontoref_action_list/add).
Adopting ontoref
A consumer project needs exactly two artifacts:
# 1. Copy the entry point wrapper
cp templates/scripts-ontoref scripts/ontoref
chmod +x scripts/ontoref
# 2. Initialize config
mkdir -p .ontoref
cp templates/ontoref-config.ncl .ontoref/config.ncl
Or run the adoption mode interactively:
./ontoref --actor developer adopt_ontoref
ONTOREF_PROJECT_ROOT is set by the consumer wrapper — one ontoref checkout serves multiple projects.
Prerequisites
- Nushell >= 0.110.0
- Nickel (for schema evaluation)
- Rust toolchain (for building crates)
- Just (for CI recipes)
To build ontoref-daemon and ontoref-reflection with NATS/SurrealDB support, the
stratumiops repo must be checked out at ../../../stratumiops. Without it, build without
default features:
cargo build -p ontoref-daemon --no-default-features
cargo build -p ontoref-ontology # always standalone
Development
cargo check-all # check all targets + features
cargo test-all # run full test suite
just ci-lint # clippy + TOML + Nickel + Markdown
just ci-full # all CI checks
nu --ide-check 50 reflection/modules/<file>.nu # validate a Nushell module
./ontoref --actor developer <mode> # run a reflection mode
License
MIT OR Apache-2.0