description = "Protocol specification and tooling layer for structured self-knowledge in software projects. Provides schemas, Nushell automation, and Rust crates so projects can describe what they are, record architectural decisions, track operational state, and execute formalized procedures as typed, queryable artifacts.",
description = "Master adoption prompt for new and existing projects: protocol infrastructure, ontology enrichment, config surface (nickel-validated-overrides + ConfigFields derive), API surface (#[onto_api]), and manifest self-interrogation (capabilities/requirements/critical_deps). Orchestrates all other templates.",
description = "Focused prompt for populating capabilities[], requirements[], and critical_deps[] in manifest.ncl. Called from Phase 5 of project-full-adoption-prompt.",
description = "Guide for vendoring frontend JS dependencies locally: directory layout (assets/vendor/), just recipe structure (assets.just with pinned version variables), Tera template integration, CDN asset verification steps, and agent execution checklist. Reusable across any ontoref-protocol project with a static-file-serving daemon.",
description = "Ordered list of directories added to NICKEL_IMPORT_PATH when invoking nickel.",
rationale = "Ontoref resolves ontology schemas, ADRs, and reflection schemas through this path list. Order matters: earlier entries shadow later ones.",
rationale = "All fields are optional — absent fields use the daemon's built-in CLI defaults. Set only when the defaults need project-specific tuning without rebuilding the binary.",
summary = "Typed NCL schemas for nodes, edges, ADRs, state, gates, and manifests — the contract layer that projects implement to describe themselves.",
rationale = "Projects need a contract layer to describe what they are — not just code comments. NCL provides typed, queryable, git-versionable schemas with contract enforcement at export time. Alternatives (TOML/JSON/YAML) lack contracts; Rust-only structs are not adoption-friendly.",
how = "ontology/schemas/ defines all type contracts (core, manifest, gate, state, content). adrs/adr-schema.ncl defines the ADR lifecycle contract with typed constraints (Cargo/Grep/NuCmd/ApiCall/FileExists checks). ontology/defaults/ exposes builders (make_node, make_edge, make_adr) so consumer projects never write raw NCL records. nickel export validates against declared contracts before any JSON reaches Rust or Nushell.",
summary = "HTTP UI (11 pages), 33 MCP tools, annotated API catalog, SSE notifications, per-file versioning, and NCL export cache.",
rationale = "Agents and developers need a queryable interface to ontology state without spawning nickel on every request. The NCL export cache reduces full-sync from ~2m42s to <30s. MCP tools give agents structured access to every capability without screen-scraping the CLI. ADR-002 records the architectural decision to extract the daemon; ADR-007 covers the #[onto_api] catalog pattern; ADR-008 covers the config override layer.",
how = "crates/ontoref-daemon uses axum for HTTP. #[onto_api(...)] proc-macro + inventory::submit! registers every route at link time; GET /api/catalog aggregates via inventory::collect!. NclCache (DashMap<PathBuf, CachedExport>) keyed on path + mtime. File watcher (notify) triggers cache invalidation and drift detection after 15s debounce. MCP over stdio and streamable-HTTP.",
summary = "19 executable NCL DAG workflows with typed steps, dependency graphs, 5 error strategies, actor filtering, guards (pre-flight constraint checks that block execution on violations), and convergence loops (re-execute until a condition is met). Modes cover sync, validation, content generation, project scaffolding, ADR lifecycle, and protocol adoption.",
rationale = "Structured procedures expressed as typed DAGs rather than ad-hoc scripts. Every step has a declared dep graph — the executor validates it before running. Agent-safe: modes are NCL contracts, not imperative scripts, so agents can read and reason about them before execution. Guards implement the Active Partner pattern — the protocol pushes back before executing if constraints are violated. Convergence implements the Refinement Loop pattern — modes iterate until a condition is met rather than running once blindly.",
how = "crates/ontoref-reflection loads a mode NCL file, validates the DAG contract (no cycles, declared deps exist), then executes steps via Nushell subprocesses. Each step declares: id, action, cmd, actor, depends_on (Always/OnSuccess/OnFailure), on_error (Stop/Continue/Retry/Fallback/Branch), and verify. Guards run before steps — each has a cmd, reason, and severity (Block/Warn). Converge runs after steps — condition cmd checked, re-executes up to max_iterations using RetryFailed or RetryAll strategy.",
summary = "Persistent execution tracking for mode runs: start runs, report steps with status/artifacts/warnings, validate dependency satisfaction, verify mode completion. File-based storage under .coder/<actor>/runs/ as JSONL.",
rationale = "Mode execution without tracking is fire-and-forget. Agents and CI need to resume interrupted runs, audit which steps passed or failed, and verify all required steps completed before declaring success. File-based storage keeps tracking git-versionable and debuggable without requiring a database.",
how = "ontoref run start <mode> creates a run directory with run.json metadata and empty steps.jsonl. step report validates the step exists in the mode DAG and that blocking dependencies (OnSuccess) are satisfied before appending. mode complete checks all steps are reported and no Stop-strategy failures block completion. current.json tracks the active run per actor.",
summary = "Form-driven prompt composition UI: select NCL form templates, fill structured fields, preview assembled markdown, send to AI providers, or export as .plan.ncl with execution DAG and lifecycle FSM (Draft/Sent/Accepted/Executed/Archived).",
rationale = "Agents need structured task input, not free-text prompts. Forms enforce required fields and typed options. Plans decouple task definition from execution — a plan can be reviewed before running, and its status tracked across sessions. The compose UI bridges form schemas to AI provider APIs without custom integration per provider.",
how = "reflection/forms/*.ncl define form schemas (elements: section_header/text/select/multiselect/editor/confirm). Daemon UI (/ui/compose) renders forms dynamically, assembles markdown from field values, and offers two actions: (1) send to AI provider via HTTP, (2) save as .plan.md + .plan.ncl. Plan NCL carries template ID, field values, linked backlog items, linked ADRs, and an optional execution DAG referencing modes. Plan status is a 5-state FSM tracked in the NCL file.",
summary = "Work item tracking (Todo/Wish/Idea/Bug/Debt) with priority, status lifecycle, and typed graduation: items promote to ADRs, reflection modes, state transitions, or PR items via ontoref backlog promote. Notification-based approval workflow for status changes.",
rationale = "Work items are not flat lists — they have destinations. A bug graduates to a fix PR. An idea graduates to an ADR. A wish graduates to a reflection mode. Typed graduation makes the promotion path explicit and machine-readable, enabling agents to propose promotions and humans to approve them via the notification system.",
how = "reflection/backlog.ncl stores items typed by reflection/schemas/backlog.ncl (Item with graduates_to: Adr/Mode/StateTransition/PrItem). CLI commands: backlog add/done/cancel/promote/propose-status/approve. propose-status emits a custom notification (backlog_review) to the daemon; admin approves via notification UI, triggering the status update. roadmap command cross-references items with state.ncl dimensions.",
summary = "Event broadcast system with SSE streaming, per-actor acknowledgment, custom event emission, and cross-project notifications. Supports approval workflows via custom notification kinds (e.g. backlog_review). Ring buffer storage with configurable retention.",
rationale = "File watchers detect changes but actors need to be notified, not poll. SSE provides real-time push without WebSocket complexity. Per-actor ACK prevents one actor's acknowledgment from hiding notifications from others. Custom events enable approval workflows without a separate messaging system.",
how = "crates/ontoref-daemon/src/notifications.rs implements a per-project ring buffer (DashMap<project, Vec<Notification>>, default 256 entries). File changes emit OntologyChanged/AdrChanged/ReflectionChanged events. User code emits custom events via push_custom(kind, title, payload, source_actor, source_project). SSE broadcast via tokio::broadcast::Sender. Per-token ACK tracking (ack_all/ack_one). Backlog propose-status uses this for approval workflows.",
summary = "Structured knowledge capture across actor sessions: init author workspaces, record JSON entries to queryable JSONL, triage inbox markdown into categories, publish to shared space with attribution, graduate to committed knowledge. 9-step DAG workflow.",
rationale = "Session knowledge evaporates between conversations. The coder pipeline captures insights, decisions, and investigations as structured entries — immediately queryable via coder log, promotable across actor boundaries, and graduable to committed project knowledge. Process memory bridges the gap between ephemeral sessions and persistent project knowledge.",
how = "coder-workflow mode (9 steps): init-author creates .coder/<author>/ with inbox/ and author.ncl. record-json appends structured entries to entries.jsonl. dump-markdown copies raw files to inbox. triage classifies inbox files into categories with companion NCL. query filters entries by tag/kind/domain/author. publish promotes entries to .coder/general/<category>/ with attribution. graduate copies to reflection/knowledge/. validate-ontology-core/state ensure ontology reflects new knowledge.",
summary = "Persistent question-answer pairs captured during development sessions, typed by QaEntry schema, with concurrent-safe NCL mutations, tag-based queries, verification status, and cross-references to ontology nodes and ADRs.",
rationale = "Recurring questions deserve persistent answers. Q&A entries bridge session boundaries — knowledge captured in one conversation is available in all future sessions. NCL storage keeps entries git-versionable and queryable without a database. ADR-003 records the decision to persist Q&A as NCL rather than browser storage.",
how = "reflection/qa.ncl stores entries typed by reflection/schemas/qa.ncl (QaEntry: id, question, answer, actor, tags, related, verified). crates/ontoref-daemon/src/ui/qa_ncl.rs performs line-level NCL surgery for add/update/remove with NclWriteLock for concurrency safety. Auto-incrementing IDs (qa-001, qa-002...). Accessible via MCP (ontoref_qa_list/add), HTTP (/qa-json), and CLI.",
summary = "Declarative form schemas in NCL with typed elements (text/select/multiselect/editor/confirm/section), dual backend execution (CLI interactive prompts or daemon HTTP), and integration with the compose pipeline and template generation.",
rationale = "Structured input collection avoids free-text ambiguity. Forms declared as NCL schemas are versionable, composable, and renderable by both CLI and web UI without separate implementations. The same form drives interactive terminal prompts and web form submission.",
how = "reflection/forms/*.ncl define form schemas as arrays of typed elements. form list discovers available forms. form run <name> --backend cli|daemon executes the form interactively or via HTTP. Collected field values feed into the compose pipeline (prompt assembly), template rendering (J2), or direct mode execution. Forms for ADR creation, project onboarding, backlog items, and config editing.",
summary = "Jinja2 template rendering composing data from ontology nodes, crate metadata, ADRs, and mode definitions to generate NCL files, Nushell scripts, config variants, and adoption artifacts.",
rationale = "Code generation from project knowledge eliminates manual transcription between the ontology and implementation artifacts. Templates bridge the gap between typed NCL declarations and executable scripts or config files.",
how = "reflection/templates/*.j2 are Jinja2 templates processed by generator.nu. Templates extract data from ontology (nodes, edges), crate metadata (Cargo.toml), ADRs (constraints), and modes (steps). Output includes: adr.ncl.j2 (ADR files from form data), adopt_ontoref.nu.j2 (adoption scripts), create_project.nu.j2 (project scaffolding), config-production.ncl.j2 (config variants). describe.nu also supports per-section Tera templates in layouts/.",
rationale = "Projects need queryable self-knowledge at different abstraction levels. A human needs a different view than an agent. describe provides semantic zoom — from one-line project identity to full constraint sets with check commands. This is the primary interface for agents to orient themselves before acting.",
how = "reflection/modules/describe.nu implements 10 subcommands, each collecting data from NCL exports (ontology, ADRs, manifest, backlog, modes) and rendering as text (human) or JSON (agent). Actor filtering applies to API routes, mode visibility, and constraint relevance. describe guides aggregates all subcommands into a single comprehensive output for agent cold-start.",
summary = "Background file watcher detecting divergence between .ontology/ declarations and actual project artifacts. 7-step sync mode: scan project structure, diff against ontology, detect doc drift (Jaccard similarity), propose patches, review, apply, verify. Emits ontology_drift notifications when drift is found.",
rationale = "Ontology declarations rot when code evolves without updating .ontology/core.ncl. Passive detection catches drift before it compounds. The sync mode bridges observation to action — detect, propose, and apply in a structured DAG rather than manual file editing.",
how = "crates/ontoref-daemon/src/ui/drift_watcher.rs watches crates/, .ontology/, adrs/, reflection/modes/ for changes. After 15s debounce, runs sync scan + sync diff. If MISSING/STALE/DRIFT/BROKEN items found, emits ontology_drift notification. sync-ontology mode (7 steps) provides the full remediation workflow: scan extracts pub API via cargo doc JSON, diff categorizes divergence, propose generates NCL patches, apply writes changes, verify runs nickel typecheck.",
summary = "Configurable shortcut grid mapping UI buttons to reflection mode execution. Declared in .ontoref/config.ncl with id, label, icon, category, mode reference, and actor ACL. One-click mode execution from the daemon UI without CLI.",
rationale = "Frequently used modes (sync-ontology, generate-mdbook, coder-workflow) need one-click access. The quick actions grid reduces friction between knowing a mode exists and executing it — especially for developers who prefer the UI over CLI.",
how = ".ontoref/config.ncl declares quick_actions array. Daemon UI (/actions) renders a categorized grid of action cards. Click triggers daemon handler run_action_by_id() which spawns tokio::process::Command with ./ontoref run <mode_id>. New actions can be added via MCP (ontoref_action_add) or by editing config.ncl directly.",
summary = "Progressive, idempotent protocol upgrades for consumer projects. Each migration carries a typed check (FileExists/Grep/NuCmd) and human-readable instructions. No state file — the check result IS the applied state. Consumer projects run ontoref migrate pending to discover and apply upgrades.",
rationale = "Protocol changes that only apply to ontoref itself are useless for the ecosystem. The migration system is the propagation mechanism — without it, consumer projects never learn about protocol evolution. ADR-010 records this decision.",
how = "reflection/migrations/NNNN-slug.ncl files define migrations with id, slug, description, check (tag + parameters), and instructions. ontoref migrate list shows all migrations. migrate pending filters to unapplied (check fails). migrate show <id> displays instructions. Checks are idempotent: FileExists tests path existence, Grep tests pattern presence, NuCmd runs a Nushell expression and checks exit code.",
summary = "Structured config system: NCL contracts validate all fields, override-layer mutation preserves original files, zero-maintenance field registry via #[derive(ConfigFields)] + inventory auto-discovers which Rust struct consumes which NCL field, coherence endpoint detects unclaimed fields and consumer fields missing from NCL export.",
rationale = "Config drift between NCL declarations and Rust consumers is invisible until runtime. The config coherence system makes it detectable at build time. Override-layer mutation ensures original NCL files (with comments, contracts, formatting) are never modified — changes are always additive. ADR-008 records this decision.",
how = "crates/ontoref-daemon/src/config.rs defines DaemonRuntimeConfig. #[derive(ConfigFields)] on Rust structs registers consumed fields via inventory::submit!. GET /config/coherence cross-references NCL export keys against registered consumers. .ontoref/contracts.ncl defines LogConfig, DaemonConfig contracts. config show/verify/audit/apply CLI commands for inspection and mutation.",
summary = "CLI and form-driven onboarding for new projects into the ontoref protocol: scaffolds .ontology/, adrs/, reflection/, .ontoref/config.ncl, and registers the project with the daemon. Includes templates for project.ncl and remote-project.ncl.",
rationale = "Adoption friction is the main barrier to protocol spread. Onboarding must be a guided, repeatable process — not a manual checklist. The adopt_ontoref mode and forms reduce the first adoption to answering structured questions.",
how = "reflection/modes/adopt_ontoref.ncl orchestrates the full onboarding DAG. reflection/forms/adopt_ontoref.ncl collects project metadata. reflection/templates/adopt_ontoref.nu.j2 generates the adoption script. templates/ provides starter files for all protocol directories. install/gen-projects.nu handles daemon project registration.",
summary = "Landing page at assets/web/ describing the ontoref protocol to external audiences. Bilingual (EN/ES), covers protocol layers, yin/yang duality, crates, and adoption path.",
rationale = "The protocol needs a public-facing explanation beyond the README. The landing page serves as the first point of contact for potential adopters.",
how = "assets/web/src/index.html is the source. assets/web/index.html is the built output. README.md links to it. assets/architecture.svg provides the visual architecture diagram.",
summary = "Persistent bookmark store for ontology graph search results. Entries typed as BookmarkEntry with node cross-references, sequential IDs, concurrent-safe NCL mutations via NclWriteLock. Accessible from daemon search UI and MCP.",
rationale = "Graph exploration sessions produce valuable search paths that are lost when the page reloads. Bookmarks persist the trail of ontology exploration across sessions.",
how = "reflection/search_bookmarks.ncl stores entries typed by reflection/schemas/search_bookmarks.ncl. crates/ontoref-daemon/src/ui/search_bookmarks_ncl.rs performs line-level NCL surgery with NclWriteLock. Sequential IDs (sb-001, sb-002...). MCP tool ontoref_bookmark_add for agent access.",
impact = "All reflection modes and the ./ontoref dispatcher are Nushell scripts. Without Nu nothing executes — no mode runs, no describe subcommands, no sync.",
provision = "https://www.nushell.sh/ — cargo install nu or OS package manager.",
used_for = "Schema evaluation, contract enforcement, config export, ADR parsing. Every nickel export call in the daemon cache and in Nushell modules.",
failure_impact = "Total loss of typed schema layer. All NCL export operations fail. Daemon cache inoperable. Config override mutation cannot validate before committing. describe guides and ontoref_guides MCP tool return empty data.",
mitigation = "Pin to a specific Nickel release in PATH. Nickel is a subprocess dep (never linked into Rust binary) — breakage manifests at runtime as nickel export exit code != 0, which all callers handle gracefully (daemon-export-safe returns null, callers use | default []).",
},
m.make_critical_dep {
id = "inventory",
name = "inventory",
ref = "crates.io: inventory 0.3",
used_for = "#[onto_api] HTTP catalog registration and #[derive(ConfigFields)] config coherence registry. Both use inventory::submit! at link time; GET /api/catalog and GET /config/coherence use inventory::iter! at runtime.",
failure_impact = "GET /api/catalog returns empty. Config coherence endpoint loses Rust struct field data. ontoref_api_catalog MCP tool blind. API version change would require updating both onto_api and ConfigFields derive macros simultaneously.",
mitigation = "inventory uses linker sections (zero runtime overhead). Version is pinned in Cargo.toml. ontoref-derive and ontoref-ontology both declare it — version must stay in sync.",
},
m.make_critical_dep {
id = "axum",
name = "axum",
ref = "crates.io: axum",
used_for = "All 11 UI pages and REST API endpoints in ontoref-daemon. Router, handlers, extractors, middleware.",
failure_impact = "Daemon does not compile. Full HTTP surface down: UI, REST API, MCP over HTTP, session management, config surface endpoints.",
mitigation = "ontoref-ontology and the ./ontoref CLI are axum-free. Reflection modes, ADR tooling, and describe subcommands continue working without the daemon.",
