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](adrs/adr-001-protocol-as-standalone-project.ncl))
- 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](adrs/adr-002-daemon-for-caching-and-notification-barrier.ncl))
- 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](adrs/adr-003-qa-and-knowledge-persistence-as-ncl.ncl))

### 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.*