ontoref/README.md

<p align="center">
  <img src="assets/ontoref-logo.svg" alt="ontoref" width="320" />
</p>

<br>

**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` | `.ontology/` NCL → typed Rust structs: Node, Edge, Dimension, Gate, Membrane. Graph traversal, invariant queries. Zero deps. |
| `ontoref-reflection` | NCL DAG contract executor: ADR lifecycle, step dep resolution, config seal. `stratum-graph` + `stratum-state` required. |
| `ontoref-daemon` | HTTP UI (10 pages), actor registry, notification barrier, MCP (19 tools), search engine, SurrealDB, NCL export cache. |

`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** — 19 tools over stdio and streamable-HTTP. Categories: nodes, ADRs, modes,
backlog, Q&A, sessions, search, notifications. Representative subset:

| 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/<file>.nu  # validate a Nushell module
./ontoref --actor developer <mode>           # run a reflection mode
```

## License

MIT OR Apache-2.0