**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 ```text 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: ```sh # 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: ```sh ./ontoref --actor developer adopt_ontoref ``` `ONTOREF_PROJECT_ROOT` is set by the consumer wrapper — one ontoref checkout serves multiple projects. ## Prerequisites - [Nushell](https://www.nushell.sh/) >= 0.110.0 - [Nickel](https://nickel-lang.org/) (for schema evaluation) - Rust toolchain (for building crates) - [Just](https://just.systems/) (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: ```sh cargo build -p ontoref-daemon --no-default-features cargo build -p ontoref-ontology # always standalone ``` ## Development ```sh 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/.nu # validate a Nushell module ./ontoref --actor developer # run a reflection mode ``` ## License MIT OR Apache-2.0