ontoref/CHANGELOG.md

Changelog

All notable changes to ontoref are documented here. ADRs referenced below live in adrs/ as typed Nickel records.

---

[Unreleased]

Protocol

• ADR-001 accepted: ontoref extracted as a standalone protocol project, independent of stratumiops versioning and release cycle. Consumer projects adopt via scripts/ontoref wrapper + .ontoref/config.ncl. (adr-001)
• ADR-002 accepted: ontoref-daemon introduced as optional persistent daemon for NCL export caching (keyed by path+mtime), actor registry (developer/agent/CI), and notification barrier (pre-commit hook, fail-open). Supersedes stratumiops ADR-007. (adr-002)
• ADR-003 accepted: Q&A and accumulated operational knowledge persist to reflection/qa.ncl — typed NCL, git-versioned, accessible via MCP tools and HTTP endpoints. localStorage eliminated. Q&A entries survive session boundaries and are queryable by any actor. (adr-003)

Crates

• ontoref-ontology: Rust crate for loading .ontology/*.ncl as typed structs (Core, Gate, State). Zero stratumiops dependencies.
• ontoref-reflection: Rust crate for loading, validating, and executing Reflection modes as NCL DAG contracts. Optional nats feature (path dep: platform-nats).
• ontoref-daemon: Rust crate providing HTTP API (axum), DashMap-backed NCL export cache, notify-based file watcher, and actor registry. Optional db feature (path dep: stratum-db) and nats feature (path dep: platform-nats).

Daemon — Q&A NCL Persistence (crates/ontoref-daemon/src/ui/qa_ncl.rs)

Line-level NCL surgery for reflection/qa.ncl — same pattern as backlog_ncl.rs. No AST parsing, no nickel-lang-core dependency.

• add_entry — appends a typed QaEntry block before ], array close; generates sequential qa-NNN ids
• update_entry — in-place field mutation via bidirectional scan (question + answer fields)
• remove_entry — removes the full block by id using backward scan for { and forward scan for },

HTTP endpoints (all under #[cfg(feature = "ui")] except read-only GET):

• GET /qa-json — export all Q&A entries as JSON (read-only, always enabled)
• POST /qa/add — append new entry; returns generated id
• POST /qa/delete — remove entry by id; invalidates NCL cache
• POST /qa/update — mutate question + answer fields by id; invalidates NCL cache
• GET /actions/run / POST /actions/run — execute a quick action by id; spawns ./ontoref <mode>

Server-side hydration: qa.html receives entries as Tera context variable, embeds SERVER_ENTRIES JSON literal in the page <script> — no fetch round-trip on load.

Daemon — MCP Tools (crates/ontoref-daemon/src/mcp/mod.rs)

Four new MCP tools exposed to AI agents:

Tool	Description
ontoref_qa_list	List Q&A entries with optional filter substring match. Never triggers ontology sync.
ontoref_qa_add	Append a new Q&A entry to reflection/qa.ncl; invalidates NCL cache.
ontoref_action_list	List all quick actions from .ontoref/config.ncl export.
ontoref_action_add	Create a new reflection mode at reflection/modes/<id>.ncl and register it as a quick action.

Constraint: ontoref_qa_list and ontoref_qa_add never trigger apply steps or modify .ontology/ files (enforced by ADR-003).

Daemon — Passive Drift Observation (crates/ontoref-daemon/src/ui/drift_watcher.rs)

Background observer bridging Yang code artifacts with Yin ontology declarations:

• Watches crates/, .ontology/, adrs/, reflection/modes/ via notify file watcher
• 15-second debounce window before triggering scan
• Spawns ./ontoref sync scan && ./ontoref sync diff as read-only subprocesses
• Parses stdout for MISSING / STALE / DRIFT / BROKEN markers
• Emits ontology_drift notification via push_custom when any drift is found
• Never applies changes automatically — apply remains a deliberate human or agent act

Started from main.rs under #[cfg(feature = "ui")]; failure to start is non-fatal (logged as warning).

Tooling

• reflection/modules/: 16 Nushell operational modules (adr.nu, backlog.nu, coder.nu, describe.nu, sync.nu, etc.)
• reflection/modes/: 10 NCL DAG operational modes including adopt_ontoref, sync-ontology, coder-workflow, create-pr
• reflection/forms/: 7 interactive NCL forms for ADR lifecycle, backlog, and adoption
• templates/: Consumer-facing adoption templates (ontoref-config.ncl, ontology/, scripts-ontoref)
• ./ontoref: Bash entry point with actor auto-detection, advisory file locking, and Nushell version guard (>= 0.110.0)

Self-Description — on+re Update

.ontology/core.ncl updated with 3 new Practice nodes and 9 new edges:

Node	Pole	Description
qa-knowledge-store	Yin	Q&A entries as typed NCL — accumulated knowledge queryable by any actor
quick-actions	Yang	Runnable shortcuts over reflection modes; configured in .ontoref/config.ncl
drift-observation	Spiral	Passive bridge between Yang code artifacts and Yin ontology declarations

New edges: qa-knowledge-store → dag-formalized, qa-knowledge-store → coder-process-memory, ontoref-daemon → qa-knowledge-store, quick-actions → reflection-modes, quick-actions → ontoref-daemon, describe-query-layer → quick-actions, drift-observation → ontoref-daemon, drift-observation → ontology-vs-reflection, drift-observation → reflection-modes.

Previous state: 4 axioms, 2 tensions, 9 practices. Current: 4 axioms, 2 tensions, 12 practices.

reflection/schemas/qa.ncl — QaStore and QaEntry types (id, question, answer, actor, created_at, tags, related, verified). reflection/qa.ncl — typed store file, conforms to QaStore contract, Nickel typecheck must pass.

---

ontoref uses its own ADR system to track decisions. Architectural rationale lives in adrs/, not in this file.