Arch Personal Prov

## The 7 Problems It Solves

01

### Decisions Without Memory

- Architectural choices made in chat, forgotten after rotation
- No machine-queryable source of why something exists
- ADRs as typed Nickel: invariants, constraints, supersession chain
- Hard constraints enforced at every operation

02

### Invisible Configuration Drift

- Configs change outside any review cycle
- No audit trail linking change to PR or ADR
- Rollback requires manual file archaeology
- Sealed profiles: sha256 hash, full history, verified rollback

03

### Agents Without Context

- LLMs start each session with zero project knowledge
- Same mistakes, same questions, no accumulation across operations
- Actor registry tracks each session token, type, current mode, last seen — persisted to disk
- MCP tools give agents direct DAG read/write: nodes, ADRs, backlog, Q&A
- Composed tasks shared via daemon — multiple actors see the same operational context live

04

### Scattered Project Knowledge

- Guidelines in wikis, patterns in docs, decisions in Slack
- No single source queryable by humans, agents, and CI equally
- `.ontology/` separates three orthogonal concerns: `core.ncl` (what IS) · `state.ncl` (where we ARE vs want to BE) · `gate.ncl` (when READY to cross a boundary)
- `reflection/` reads all three and answers self-knowledge queries — an agent understands the project without reading code, only by consulting the declarative graph

05

### Protocol Fragmentation

- Each project re-invents its own conventions
- No shared contract for how operations are defined and executed
- Reflection modes: typed DAG contracts for any workflow
- One protocol adopted per-project, without enforcing uniformity

06

### Knowledge Lost Between Sessions

- Q&A answered in one session forgotten by the next
- Agent re-asks questions already answered in previous sessions
- Q&A Knowledge Store: typed NCL, git-versioned, persists across browser resets
- Notification barrier surfaces drift to agents proactively — `pre_commit`, `drift`, `ontology_drift` signals block until acknowledged

07

### Decisions Without a Map

- Personal and professional decisions made against implicit, unverifiable assumptions
- No queryable model of what you never compromise
- No structured way to ask: does this opportunity violate who I am?
- ontoref as personal operational ontology — same `core/state/gate` files applied to life, career, and ecosystem dimensions
- `jpl validate "accept offer"` → invariants_at_risk, relevant edges, verdict

## Ontology & Reflection — Yin and Yang

### Yin — The Ontology Layer

What must be true

- Invariants — axioms that cannot change without a new ADR
- Tensions — structural conflicts the project navigates, never resolves
- Practices — confirmed patterns with artifact paths to real files and declared ADR validators
- Gates — membranes controlling readiness thresholds
- Dimensions — current vs desired state, with transition conditions
- Q&A Knowledge Store — accumulated Q&A persisted to NCL, git-versioned, queryable by any actor

### Yang — The Reflection Layer

How things move and change

- Modes — typed DAG workflow contracts (preconditions, steps, postconditions)
- Forms — parameter collection driving modes
- ADR lifecycle — Proposed → Accepted → Superseded, with constraint history
- Actors — developer / agent / CI, same protocol, different capabilities
- Config seals — sha256-sealed profiles, drift detection, rollback
- Quick Actions — runnable shortcuts over modes; configured in `.ontoref/config.ncl`
- Passive Drift Observer — watches code changes, emits `ontology_drift` notifications with missing/stale/drift/broken counts

Ontology without Reflection = correct but static. Perfect invariants with no operations = dead documentation.
Reflection without Ontology = fluid but unanchored. Workflows that forget what they protect.

The protocol lives in coexistence.

DECLARATIVE LAYER · Nickel
`.ontology/` · `adrs/` · `reflection/schemas/`
Strong types, contracts, enums. Fails at definition time, not at runtime.
OPERATIONAL LAYER · Nushell
`adr` · `register` · `config` · `backlog` · `forms` · `describe`
Typed pipelines over structured data. No text streams.
ENTRY POINT · Bash → Nu
`ontoref` · actor detection · advisory locking · `ONTOREF_IMPORT_PATH`
Single entry point per project. Detects actor (developer/agent/CI), acquires lock, dispatches to correct Nu module.
KNOWLEDGE GRAPH · .ontology/
nodes · invariants · tensions · gates · dimensions · states
The project knows what it knows. Actor-agnostic. Machine-queryable via `nickel export`.
RUNTIME LAYER · Rust + axum
`ontoref-daemon` · `ontoref-ontology` · `ontoref-reflection` · `search engine` · `notification barrier` · `SurrealDB (optional)`
Optional persistent daemon. NCL export cache, HTTP UI (11 pages), MCP server (29 tools), actor registry, notification store, search engine, SurrealDB persistence. Never a protocol requirement.
ADOPTION LAYER · Per-project
`.ontoref/config.ncl` · `ontoref` CLI · `adopt_ontoref` mode
Each project maintains its own `.ontology/` data. Ontoref provides the schemas, modules, and migration scripts. Zero lock-in.

## Crates & Tooling

🧩

### ontoref-ontology

- Load and query `.ontology/` NCL files as typed Rust structs
- Node, Edge, Dimension, Gate, Membrane types — `Node` carries `artifact_paths` and `adrs`, both `serde(default)`
- Graph traversal: callers, callees, impact queries
- Invariant extraction and constraint validation
- Zero stratumiops dependencies — minimal adoption surface (ADR-001)

🔄

### ontoref-reflection

- Execute reflection modes as typed NCL DAG contracts
- Step execution with dependency resolution
- ADR lifecycle: Proposed → Accepted → Superseded
- Config seal and rollback operations
- `stratum-graph` + `stratum-state` required; `platform-nats` feature-gated

📜

### Nushell Modules

- `store.nu` — SurrealDB-backed cache with NCL export
- `sync.nu` — ontology code synchronization
- `describe.nu` — actor-aware project self-knowledge
- `coder.nu` — structured session records
- 16 modules total — one per operational domain

⚙️

### Nickel Schemas

- Core ontology types: Node, Edge, Pole, AbstractionLevel
- State machine types: Dimension, Transition, Gate, Membrane
- ADR schema: Constraint, Severity, Status, supersession
- Reflection schema: Mode, Step, OnError, Dependency

🖥️

### ontoref-daemon · HTTP & UI

- HTTP UI (axum + Tera): 11 pages — dashboard, graph, search, sessions, notifications, backlog, Q&A, actions, modes, compose, manage/login, manage/logout
- Graph node detail panel: artifacts, connections, and ADR validators — each ADR is a clickable link that opens the full record via `GET /api/adr/{id}`
- Actor registry (DashMap): token, type (developer / agent / CI), registered_at, last_seen, current_mode — serializable snapshot
- Notification barrier: `pre_commit` · `drift` · `ontology_drift` — pre-commit hook polls & blocks on ack
- Compose / live sharing: mode forms rendered interactively, `./ontoref` dispatched server-side, shared across actors
- File watcher (`notify`): passive drift observer, no polling

⚡

### ontoref-daemon · MCP & Data

- MCP server: stdio + streamable-HTTP, 19 tools — nodes, ADRs, modes, backlog, Q&A, sessions, search, notifications
- Search engine: full-text across nodes / ADRs / reflection modes — returns kind · id · title · snippet · score
- SurrealDB persistence (optional `--db`): actor sessions, seeded ontology tables, search index, notification history — fail-open
- NCL export cache: avoids repeated `nickel export` on unchanged files
- `db` + `nats` feature flags — builds standalone with `--no-default-features`

### Adopt in Any Project

`ontoref setup` wires up any new or existing project — idempotent scaffold with optional auth key bootstrap.

stratumiops Master orchestration repo
vapora AI agent orchestration
kogral Knowledge graph + MCP
syntaxis Project orchestration
provisioning Declarative IaC
your-project Any codebase
# Onboard a new project (idempotent; kind: Service by default)
ontoref setup
ontoref setup --kind Library
ontoref setup --gen-keys ["admin:dev" "viewer:ci"] # bootstrap auth keys once
# Query the project self-knowledge
ontoref describe project
ontoref describe constraints
ontoref describe impact ontology-node-id
# ADR lifecycle
ontoref adr new --title "Adopt Nickel for configuration"
ontoref adr list --status Accepted

## Project Types — Domain Extensions

The CLI adapts to your project type. `ontoref setup --kind X` writes the `repo_kind` field into your manifest and activates domain-specific commands under a short alias. Domain modules extend the ontology schema, add CLI subcommands, and surface new daemon UI pages — without touching the core protocol.

Generic
Library · Service · PublishedCrate

- Standard protocol surface — no domain activation
- Full ontology, ADR, reflection mode, and backlog support
- Daemon UI: /overview · /graph · /adrs · /backlog · /coder
- No alias — all commands via `ontoref`

ontoref setup --kind Library
ontoref describe project
ontoref adr list --status Accepted
Personal Ontology
PersonalOntology — alias: personal

- Career history as queryable graph: skills, talks, publications, positioning
- CFP pipeline with stage tracking (Watching → Delivered)
- Opportunities and content lifecycle management
- Daemon UI: /career · /personal

ontoref setup --kind PersonalOntology
personal career skills --tier Expert
personal cfp --stage Drafting
→ Personal domain docs
DevWorkspace / Mixed
DevWorkspace · Mixed — alias: prov

- Infrastructure state as FSM: dimensions, transitions, blockers, catalysts
- Upstream/downstream connection graph and membrane gate status
- Workspace card: identity, clusters, platform capabilities
- Daemon UI: /provisioning (State · Connections · Gates)

ontoref setup --kind DevWorkspace
prov state
prov connections
→ Provisioning domain docs

## Daemon & MCP — Runtime Intelligence Layer

`ontoref-daemon` is an optional persistent process. It caches NCL exports, serves 11 UI pages, exposes 29 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. The annotated API surface is discoverable at `GET /api/catalog` (populated at link time via `#[onto_api]` proc-macro). Auth is opt-in: all surfaces (CLI, UI, MCP) exchange a project key for a UUID v4 session token via `POST /sessions`; CLI injects `ONTOREF_TOKEN` as Bearer automatically. It never changes the protocol — it accelerates and shares access to it. Configured via `~/.config/ontoref/config.ncl` (Nickel, type-checked); edit interactively with `ontoref config-edit`. Started via NCL pipe bootstrap: `ontoref-daemon-boot`.

The Web UI — 12 Pages
localhost:7421/ui/{slug}/
/ Dashboard project overview, actor count, cache stats, notification count, backlog summary
/graph Graph Cytoscape.js ontology graph — nodes colored by pole (Yang=orange, Yin=blue, Spiral=purple), clickable detail panel with artifacts, connections, and ADR links that open the full record in a modal
/search Search full-text search across nodes, ADRs, reflection modes — returns kind/id/title/snippet/score
/sessions Sessions live actor registry — actor type, mode, last_seen; auth sessions (id, role, key_label, expires) for authed deployments
/notifications Notifications notification feed — pre_commit / drift / ontology_drift; ack/dismiss; emit custom; action buttons
/backlog Backlog items with priority (Critical/High/Medium/Low) and status (Open/InProgress/Done/Cancelled); add/update
/qa Q&A server-hydrated from reflection/qa.ncl; add/edit/delete; persisted as typed NCL
/actions Actions quick actions catalog from .ontoref/config.ncl; execute via POST /actions/run
/modes Modes reflection mode list from reflection/modes/ — name, description, DAG contract
/compose Compose agent task composer — renders mode forms interactively; POST /compose/send dispatches to ./ontoref; live sharing for AI actors
The MCP Server — 19 Tools

Tool | Description
--- | ---
ontoref_help | List available tools and usage
ontoref_list_projects | Enumerate all registered projects
ontoref_set_project | Set session default project context
ontoref_project_status | Full project dashboard — health, drift, actors
ontoref_describe | Architecture overview and self-description
ontoref_search | Free-text search across nodes, ADRs, modes
ontoref_get | Fetch ontology node by id
ontoref_get_node | Full ontology node with edges and constraints
ontoref_list_adrs | List ADRs filtered by status
ontoref_get_adr | Full ADR content with constraints
ontoref_list_modes | List all reflection modes
ontoref_get_mode | Mode DAG contract — steps, preconditions, postconditions
ontoref_get_backlog | Backlog items filtered by status
ontoref_backlog | Add or update_status on a backlog item
ontoref_constraints | All hard + soft architectural constraints
ontoref_qa_list | List Q&A knowledge store with optional filter
ontoref_qa_add | Persist new Q&A entry to reflection/qa.ncl
ontoref_action_list | Quick actions catalog from .ontoref/config.ncl
ontoref_action_add | Create reflection mode + register as quick action

#### SurrealDB Persistence — Optional

- Enabled with `--db` feature flag and `--db-url ws://...`
- Connects via WebSocket at startup — 5s timeout, fail-open (daemon runs without it)
- Seeds ontology tables from local NCL files on startup and on file changes
- Persists: actor sessions, seeded ontology tables, search index, notification history
- Without `--db`: DashMap-backed in-memory, process-lifetime only
- Namespace configurable via `--db-namespace`; credentials via `--db-username/--db-password`

#### Notification Barrier

- pre_commit — pre-commit hook polls `GET /notifications/pending?token=X&project=Y`; blocks git commit until all acked
- drift — schema drift detected between codebase and ontology
- ontology_drift — emitted by passive observer with missing/stale/drift/broken counts after 15s debounce
- Fail-open: if daemon is unreachable, pre-commit hook passes — commits are never blocked by daemon downtime
- Ack via UI or `POST /notifications/ack`; custom notifications via `POST /{slug}/notifications/emit`
- Action buttons in notifications can link to any dashboard page

# Configure and start the daemon (optional — protocol works without it)
ontoref config-edit # browser form → ~/.config/ontoref/config.ncl
ontoref-daemon-boot # NCL pipe bootstrap: nickel export config.ncl | daemon --config-stdin
ontoref-daemon-boot --dry-run # preview composed JSON without starting
# With SOPS-encrypted secrets merged at boot
ontoref-daemon-boot --sops secrets.enc.json
# Connect Claude Code via MCP (add to .claude/mcp.json)
{
"mcpServers": {
"ontoref": { "type": "http", "url": "http://localhost:7421/mcp" }
}
}
# Search across ontology nodes, ADRs, and reflection modes
ontoref_search({ q: "notification drift", project: "my-project" })
# Persist a Q&A entry (written to reflection/qa.ncl, git-versioned)
ontoref_qa_add({
question: "Why does ontoref-ontology have zero stratumiops deps?",
answer: "ADR-001: minimal adoption surface. Ontology crate must build standalone.",
tags: ["adr-001", "architecture"]
})
# Check live actor sessions
curl http://localhost:7421/actors
# {"sessions": [{"token": "abc123", "actor_type": "agent", "current_mode": "describe", ...}]}

## The UI in Action · Graph View

Force-directed graph of the live ontology. Nodes are typed (Axiom · Tension · Practice) and polarized (Yang · Yin · Spiral). Click any node to open its detail panel — artifacts, connections, NCL source.

Yang · Axiom
Yin · Tension
Spiral · Practice
Filter buttons · Edge labels · Node detail panel

## Technology Stack

Rust Edition 2021 Nickel Nushell 0.111+ axum Tera Templates DashMap notify MCP Protocol Cytoscape.js Server-Sent Events SurrealDB NATS JetStream SHA-256 Seals DAG Contracts shellcheck POSIX Advisory Locks

## Protocol Metrics

3 Rust Crates ontology · reflection · daemon
19 MCP Tools AI agent integration · stdio + HTTP
1 Web UI · 12 Pages dashboard · graph · search · sessions · notifications · backlog · Q&A · actions · modes · compose
6 Protocol Layers Declarative → Adoption
1 Search Engine nodes · ADRs · reflection modes
16 Nu Modules Structured data pipelines
8+ Reflection Modes DAG workflow contracts
3 Actor Types developer / agent / CI
0 Enforcement Voluntary adoption

## Structure That Remembers Why

Start with `ontoref setup`. Your project gains machine-queryable invariants, living ADRs, actor-aware operational modes, and a daemon that shares context across every actor in real time.

Explore the Protocol