description = "Onref is a protocol specification and tooling layer. It is never a runtime dependency. Projects implement the protocol; onref provides the schemas and modules to do so.",
invariant = true,
},
d.make_node {
id = "self-describing",
name = "Self-Describing",
pole = 'Yang,
level = 'Axiom,
description = "Onref describes itself using its own protocol. The .ontology/, adrs/, and reflection/ directories in this repository are onref consuming ontoref.",
description = "Onref defines contracts and patterns. There is no enforcement mechanism. Coherence is voluntary and emerges from justified adoption.",
invariant = true,
},
d.make_node {
id = "dag-formalized",
name = "DAG-Formalized Knowledge",
pole = 'Yin,
level = 'Axiom,
description = "All project knowledge — concepts, tensions, decisions, state — is formalized as directed acyclic graphs. This enables transversal queries, impact analysis, and ecosystem-level visibility.",
description = "Richer formalization produces better ecosystem visibility but increases the cost of adoption. The balance: schemas are optional layers, not mandatory gates.",
},
d.make_node {
id = "ontology-vs-reflection",
name = "Ontology vs Reflection",
pole = 'Spiral,
level = 'Tension,
description = "Ontology captures what IS (invariants, structure, being). Reflection captures what BECOMES (operations, drift, memory). Both must coexist without one dominating. This tension is onref's core identity.",
description = "Operational procedures are first-class artifacts encoded as NCL DAG contracts. Modes declare actors, steps, dependencies, and error strategies — not prose.",
description = "Session knowledge is captured as structured JSONL via coder record. Queryable, exportable, and promotable to reflection/knowledge/. The memory layer between sessions.",
description = "describe.nu aggregates all project sources and answers self-knowledge queries: what IS this, what can I DO, what can I NOT do, what tools exist, what is the impact of changing X.",
description = "Rust implementation for loading and querying .ontology/ NCL files as typed structs. Provides the Core, Gate, and State types for ecosystem-level introspection.",
artifact_paths = ["crates/ontoref-ontology/"],
},
d.make_node {
id = "ontoref-reflection-crate",
name = "Ontoref Reflection Crate",
pole = 'Yang,
level = 'Practice,
description = "Rust implementation for loading, validating, and executing Reflection modes as NCL DAG contracts against project state.",
artifact_paths = ["crates/ontoref-reflection/"],
},
d.make_node {
id = "adopt-ontoref-tooling",
name = "Adopt Ontoref Tooling",
pole = 'Yang,
level = 'Practice,
description = "Migration system for onboarding existing projects into the ontoref protocol. Provides .ontology/ stub templates, .ontoref/config.ncl template, scripts/ontoref thin wrapper, and the adopt_ontoref mode+form+script that wire everything up idempotently.",
description = "All surfaces (CLI, UI, MCP) exchange a raw key for a UUID v4 session token via POST /sessions (30-day lifetime, O(1) lookup vs O(~100ms) argon2 per request). Project keys carry role (admin|viewer) and label for audit trail. Daemon admin sessions use virtual slug '_daemon'. ONTOREF_TOKEN injected as Bearer by CLI automatically. Sessions have a stable public id (distinct from bearer token) for safe list/revoke operations. Key rotation revokes all sessions for the rotated project.",
invariant = false,
artifact_paths = [
"crates/ontoref-daemon/src/session.rs",
"crates/ontoref-daemon/src/api.rs",
"crates/ontoref-daemon/src/registry.rs",
"crates/ontoref-daemon/src/ui/login.rs",
"crates/ontoref-daemon/src/ui/auth.rs",
"reflection/modules/store.nu",
"install/resources/schemas/ontoref-project.ncl",
],
},
d.make_node {
id = "project-onboarding",
name = "Project Onboarding",
pole = 'Yang,
level = 'Practice,
description = "Idempotent onboarding via `ontoref setup`. Creates .ontoref/project.ncl, .ontoref/config.ncl (with logo auto-detection in assets/), .ontology/ scaffold, adrs/, reflection/modes/, backlog.ncl, qa.ncl, git hooks, and registers in projects.ncl. Supports --kind (repo_kind) and --parent (framework layers + browse modes for implementation children). Bootstrap key generation via --gen-keys ['admin:label' 'viewer:label']: idempotent (no-op if keys exist), hashes via daemon binary, prints passwords once.",
invariant = false,
artifact_paths = [
"reflection/bin/ontoref.nu",
"templates/project.ncl",
"templates/ontoref-config.ncl",
"templates/ontology/",
"install/gen-projects.nu",
"install/resources/schemas/ontoref-project.ncl",
],
},
d.make_node {
id = "daemon-config-management",
name = "Daemon Config Management",
pole = 'Yang,
level = 'Practice,
description = "Install and configuration infrastructure for ontoref-daemon. Global config at ~/.config/ontoref/config.ncl (Nickel, type-checked). Browser-based editing via typedialog roundtrip: form (config.ncl) → browser → Tera template (config.ncl.j2) → updated config.ncl. CI guard (check-config-sync.nu) enforces form/template parity on every commit. Global NATS topology at ~/.config/ontoref/streams.json; project-local override via nats/streams.json and NATS_STREAMS_CONFIG env var. Config validation + liveness probes via config-setup.nu.",
description = "Accumulated Q&A entries persisted as NCL — questions and answers captured during development sessions, AI interactions, and architectural reviews. Git-versioned, typed by QaEntry schema, queryable via MCP (ontoref_qa_list/add) and HTTP (/qa-json). Bridges session boundaries: knowledge is never lost between actor sessions.",
artifact_paths = [
"reflection/qa.ncl",
"reflection/schemas/qa.ncl",
"crates/ontoref-daemon/src/ui/qa_ncl.rs",
],
},
d.make_node {
id = "quick-actions",
name = "Quick Actions Catalog",
pole = 'Yang,
level = 'Practice,
description = "Runnable shortcuts over existing reflection modes. Configured as quick_actions in .ontoref/config.ncl (id, label, icon, category, mode, actors). Accessible from UI (/actions), CLI (./ontoref), and MCP (ontoref_action_list/add). New modes created via ontoref_action_add are immediately available as actions. Reduces friction between knowing a mode exists and executing it.",
description = "Background observer that bridges Yang code artifacts with Yin ontology declarations. Watches crates/, .ontology/, adrs/, reflection/modes/ for changes; after a debounce window runs sync scan + sync diff; if MISSING/STALE/DRIFT/BROKEN items are found emits an ontology_drift notification. Never applies changes automatically — apply remains a deliberate human or agent act.",
artifact_paths = [
"crates/ontoref-daemon/src/ui/drift_watcher.rs",
"reflection/modes/sync-ontology.ncl",
],
},
],
edges = [
{ from = "self-describing", to = "dag-formalized", kind = 'ManifestsIn, weight = 'High },
{ from = "self-describing", to = "adr-lifecycle", kind = 'ManifestsIn, weight = 'High },
{ from = "self-describing", to = "reflection-modes", kind = 'ManifestsIn, weight = 'High },
{ from = "ontology-vs-reflection", to = "dag-formalized", kind = 'Resolves, weight = 'High },
{ from = "ontology-vs-reflection", to = "coder-process-memory", kind = 'Resolves, weight = 'Medium },
{ from = "dag-formalized", to = "ontoref-ontology-crate", kind = 'ManifestsIn, weight = 'High },
{ from = "reflection-modes", to = "ontoref-reflection-crate", kind = 'ManifestsIn, weight = 'High },
{ from = "no-enforcement", to = "formalization-vs-adoption", kind = 'Resolves, weight = 'Medium },
{ from = "protocol-not-runtime", to = "no-enforcement", kind = 'Implies, weight = 'High },
{ from = "adr-lifecycle", to = "reflection-modes", kind = 'Complements, weight = 'Medium },
{ from = "describe-query-layer", to = "dag-formalized", kind = 'DependsOn, weight = 'High },
{ from = "coder-process-memory", to = "describe-query-layer", kind = 'Complements, weight = 'Medium },
{ from = "ontoref-daemon", to = "ontoref-ontology-crate", kind = 'Complements, weight = 'High },
{ from = "ontoref-daemon", to = "reflection-modes", kind = 'Complements, weight = 'Medium },
{ from = "protocol-not-runtime", to = "ontoref-daemon", kind = 'Contradicts, weight = 'Low,
note = "Daemon is optional runtime support, not a protocol requirement. Protocol functions without it." },
{ from = "no-enforcement", to = "adopt-ontoref-tooling", kind = 'ManifestsIn, weight = 'High,
note = "Adoption is voluntary — the tooling makes it easy but never mandatory." },
{ from = "adopt-ontoref-tooling", to = "reflection-modes", kind = 'DependsOn, weight = 'High },
{ from = "self-describing", to = "web-presence", kind = 'ManifestsIn, weight = 'Medium },
{ from = "web-presence", to = "adopt-ontoref-tooling", kind = 'Complements, weight = 'Medium },
# Q&A Knowledge Store edges
{ from = "qa-knowledge-store", to = "dag-formalized", kind = 'ManifestsIn, weight = 'High,
note = "Q&A entries are typed NCL records, git-versioned — knowledge as DAG." },
{ from = "qa-knowledge-store", to = "coder-process-memory", kind = 'Complements, weight = 'High,
note = "Q&A is the persistent layer; coder.nu is the session capture layer. Together they form the full memory stack." },
{ from = "ontoref-daemon", to = "qa-knowledge-store", kind = 'Contains, weight = 'High },
{ from = "quick-actions", to = "reflection-modes", kind = 'DependsOn, weight = 'High,
note = "Each quick action invokes a reflection mode by id." },
{ from = "quick-actions", to = "ontoref-daemon", kind = 'ManifestsIn, weight = 'Medium },
{ from = "describe-query-layer", to = "quick-actions", kind = 'Complements, weight = 'Medium,
note = "describe capabilities lists available modes; quick-actions makes them executable." },
# Drift Observation edges
{ from = "drift-observation", to = "ontoref-daemon", kind = 'ManifestsIn, weight = 'High },
{ from = "drift-observation", to = "ontology-vs-reflection", kind = 'Resolves, weight = 'Medium,
note = "Drift observer continuously monitors the gap between Yin (ontology) and Yang (code). Passive resolution — it signals drift without forcing resolution." },
{ from = "drift-observation", to = "reflection-modes", kind = 'DependsOn, weight = 'High,
{ from = "unified-auth-model", to = "ontoref-daemon", kind = 'ManifestsIn, weight = 'High },
{ from = "unified-auth-model", to = "no-enforcement", kind = 'Contradicts, weight = 'Low,
note = "Auth is opt-in per project (no keys = open deployment). When keys are configured enforcement is real, but the protocol itself never mandates it." },
{ from = "ontoref-daemon", to = "unified-auth-model", kind = 'Contains, weight = 'High },
# Project Onboarding edges
{ from = "project-onboarding", to = "adopt-ontoref-tooling", kind = 'Complements, weight = 'High,
note = "adopt-ontoref-tooling is the migration surface for existing projects; project-onboarding is the first-class setup for new projects." },
{ from = "project-onboarding", to = "unified-auth-model", kind = 'DependsOn, weight = 'Medium,
note = "--gen-keys bootstraps the first keys into project.ncl during setup." },
{ from = "project-onboarding", to = "daemon-config-management", kind = 'DependsOn, weight = 'Medium },
