ontoref/reflection/templates/update-ontology-prompt.md

Ontoref Protocol Update — Ontology Enrichment Prompt

Purpose: Bring {project_name} up to the current ontoref protocol version and enrich its ontology to reflect the project's actual state. Run this prompt in the project's Claude Code session with ontoref available.

Substitutions required before use:

• {project_name} — kebab-case project identifier
• {project_dir} — absolute path to project root

Requires: ontoref installed globally (just install-daemon from the ontoref repo).

---

Bootstrap — source ontoref env vars

Before running any direct nickel export command, source the ontoref env into the current shell. This sets NICKEL_IMPORT_PATH and ONTOREF_ROOT without launching a full command:

cd {project_dir}
. $(which ontoref) --env-only
# NICKEL_IMPORT_PATH and ONTOREF_ROOT are now available in this shell session

All nickel export commands in this prompt assume these vars are set.

---

Context for the agent

You are enriching the ontoref ontology for project {project_name}. The ontology lives in .ontology/ and the reflection layer in reflection/. Your goal is to make the ontology reflect current architectural reality — not aspirational state, not stale state.

Read the project's .claude/CLAUDE.md and any CLAUDE.md at root before starting. Understand what the project actually does. All changes must pass nickel export cleanly.

---

Phase 1 — Infrastructure: add missing v2 files

Run the infrastructure detection and update steps. These are additive — nothing is overwritten.

cd {project_dir}

# Step 1a: detect missing files
test -f .ontology/manifest.ncl    && echo "manifest: present"    || echo "manifest: MISSING"
test -f .ontology/connections.ncl && echo "connections: present" || echo "connections: MISSING"

# Step 1b: add manifest.ncl if missing (template installed with ontoref)
test -f .ontology/manifest.ncl || \
  sed 's/{{ project_name }}/{project_name}/g' \
    "$ONTOREF_ROOT/templates/ontology/manifest.ncl" > .ontology/manifest.ncl

# Step 1c: add connections.ncl if missing
test -f .ontology/connections.ncl || \
  sed 's/{{ project_name }}/{project_name}/g' \
    "$ONTOREF_ROOT/templates/ontology/connections.ncl" > .ontology/connections.ncl

# Step 1d: validate both files parse
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/manifest.ncl \
  > /dev/null && echo "manifest: ok"

nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/connections.ncl \
  > /dev/null && echo "connections: ok"

If either validation fails, read the file, fix the import path or schema mismatch, and revalidate before continuing.

---

Phase 2 — Audit: understand current state

Run these commands and read the output before making any changes to core.ncl or state.ncl.

# Full project self-description (identity, axioms, practices, gate)
ontoref describe project

# Semantic diff vs HEAD — shows what changed since last commit
ontoref describe diff

# What modes are available, what gates allow
ontoref describe guides

# Current gate state and dimension health
ontoref describe gate

# API surface available (requires daemon running)
ontoref describe api

Read the output of each command. Note:

• Which dimensions are in non-ideal states and why
• Which practices have no corresponding nodes in core.ncl
• What the diff reports as added/removed/changed since HEAD
• Whether the gate is aligned with what the project actually does today

---

Phase 3 — Enrich core.ncl

Open .ontology/core.ncl. For each of the following, apply only what is actually true:

3a. Nodes — add missing, update stale descriptions

For any practice or capability the project has implemented since the last ontology update, add a node with:

• id — kebab-case, stable identifier
• level — 'Axiom | 'Tension | 'Practice | 'Project | 'Moment
• description — one sentence, present tense, what it IS (not what it should be)
• adrs — list any ADR IDs that govern this node

Do NOT add aspirational nodes. If a feature is not yet implemented, do not add it.

3b. Edges — declare real dependencies

For any new nodes, declare edges to the nodes they depend on or implement:

{ from = "new-node-id", to = "existing-node-id", kind = 'Implements }

Valid edge kinds: 'Implements | 'Depends | 'Extends | 'Supersedes | 'Tensions

3c. Tensions — update descriptions

For tension nodes (level = 'Tension), update the description to reflect the current root cause if it has changed. Tensions describe real trade-offs the project has made, not theoretical ones.

After editing, validate:

nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/core.ncl > /dev/null

---

Phase 4 — Update state.ncl

Open .ontology/state.ncl. For each dimension:

1. Read current_state and transition conditions
2. Check whether a transition condition has been met based on recent work
3. If the project has advanced: update current_state to the new state
4. Update blocker and catalyst to reflect current reality (not stale reasoning)

Do NOT advance a dimension optimistically. Only advance if the transition condition is demonstrably met (code exists, tests pass, ADR written — not "in progress").

After editing:

nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/state.ncl > /dev/null

---

Phase 5 — Fill manifest.ncl

Open .ontology/manifest.ncl. Declare any content assets the project has:

• Branding assets (logos, icons) in assets/branding/ or equivalent
• Architecture diagrams in docs/, assets/, or architecture/
• Screenshots or demo recordings
• Agent prompt templates in reflection/templates/
• Mode step templates in reflection/templates/

For each asset, use m.make_asset with accurate source_path (relative to project root), correct kind, and a one-sentence description. Only declare assets that actually exist on disk.

Check:

ls assets/ 2>/dev/null; ls docs/ 2>/dev/null; ls reflection/templates/ 2>/dev/null

After editing:

nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/manifest.ncl > /dev/null

---

Phase 6 — Declare connections.ncl

Open .ontology/connections.ncl. Declare cross-project relationships if they exist:

• upstream — projects this one depends on or consumes APIs from
• downstream — projects that consume this one's APIs or outputs
• peers — symmetric sibling services with shared concerns

For each connection: project must be a slug registered in the shared daemon, node is an ontology node id in that project, via is "http" | "local" | "nats".

If no cross-project relationships exist, leave all arrays empty — that is valid and correct. Do NOT invent connections.

After editing:

nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/connections.ncl > /dev/null

---

Phase 7 — Migrate ADR check_hint (if present)

Check for deprecated check_hint fields:

grep -rl 'check_hint' {project_dir}/adrs/ 2>/dev/null

If any files are found, for each ADR:

1. Read the check_hint string — it describes what to verify
2. Map it to the closest typed check variant:
   • Shell command → 'NuCmd { cmd = "...", expect_exit = 0 }
   • File search (grep/rg) → 'Grep { pattern = "...", paths = ["..."], must_be_empty = true }
   • Cargo.toml dep check → 'Cargo { crate = "...", forbidden_deps = ["..."] }
   • File presence → 'FileExists { path = "...", present = true }
   • API response → 'ApiCall { endpoint = "...", json_path = "...", expected = ... }
3. Replace check_hint with check using the typed variant
4. Validate:

nickel export --import-path "$NICKEL_IMPORT_PATH" adrs/adr-NNN-*.ncl > /dev/null

---

Phase 8 — Final validation

Run all validations in sequence:

# All .ontology/ files
for f in .ontology/core.ncl .ontology/state.ncl .ontology/gate.ncl \
         .ontology/manifest.ncl .ontology/connections.ncl; do
  nickel export --import-path "$NICKEL_IMPORT_PATH" "$f" > /dev/null \
    && echo "ok: $f" || echo "FAIL: $f"
done

# All ADRs
for f in adrs/adr-*.ncl; do
  nickel export --import-path "$NICKEL_IMPORT_PATH" "$f" > /dev/null \
    && echo "ok: $f" || echo "FAIL: $f"
done

# Re-run describe diff to confirm changes are coherent
ontoref describe diff

# Final project state
ontoref describe project

---

Delivery

Report:

1. Files changed and what was changed in each
2. Nodes added / updated / removed in core.ncl
3. Dimension state transitions applied in state.ncl
4. Assets declared in manifest.ncl
5. Connections declared in connections.ncl
6. ADRs migrated from check_hint to typed check
7. Any validation errors that could not be resolved (with reason)

Do NOT commit. The developer reviews the diff before committing.