# Ontology Guardrails v0.4-pre

Status: pre-release implementation baseline
Date: 2026-06-18

These rules exist to stop future agents and developers from merging similar-looking but different NodeDC concepts.

## Core Naming Rules

1. Use canonical IDs from `CANONICAL_ENTITY_CATALOG.md`.
2. Treat aliases as aliases, not new roots.
3. If source evidence is missing, mark the entity as `pending`; do not invent implementation facts.
4. Keep `source-confirmed`, `owner-confirmed`, `product-required`, and `future-concept` separate.
5. Use `ops.card` as the canonical work object. `Issue`, `task`, `work item`, and `ticket` are aliases or subtypes.

## HUB Guardrails

- `hub.open_contour` is not an ordinary `hub.client_context`.
- `hub.public_pool_client` is a special source-backed Client used by public pool context.
- `hub.public_user` and `hub.client_user` are classifications of `hub.user`, not separate hard user tables/classes unless future source proves otherwise.
- `hub.application_card` is presentation only. Access authority belongs to `hub.application_access`, `hub.app_grant`, and `hub.app_exception`.
- Authentik, OIDC, JWT, and provider-specific auth names are implementation aliases under `ndcauth.identity` / `ndcauth.session`.

## OPS Product Guardrails

- OPS Product is the operational work/project/card layer.
- OPS Product must not be derived from ENGINE-side `server/routes/ops.js` or Agent Monitor experiments.
- Plane `Issue` maps to canonical `ops.card`.
- `ops.card_priority` is a card attribute, not a global root entity.
- `ops.responsible` is not automatically equal to `ops.assignee`; keep the distinction until source/product semantics are finalized.
- `ops.card_artifact_link` is a relation/link to outputs, not a global artifact root.

## OPS Gateway Guardrails

- OPS Gateway is the scoped MCP/API access layer for agents.
- `agent.identity` is a Gateway execution identity, not a human user and not a universal assistant persona.
- `agent.token` is an opaque credential. Do not treat it as user identity.
- `agent.scope` is a tool/capability permission. Do not confuse it with HUB/OPS roles.
- Gateway writes must remain scoped, audited, and idempotent.
- Gateway does not own raw OPS product truth. Tasker/OPS remains source of truth for projects/cards.
- HUB remains source of truth for platform user/client/application entitlement.

## ENGINE Guardrails

- ENGINE is workflow/dev environment, not the final home for heavy product UIs.
- `engine.workflow_l1` is the NodeDC canvas/workflow graph.
- `engine.workflow_l2` is a runtime/subworkflow layer, currently n8n-backed.
- `engine.workflow_l2_runtime_id` is not the same as NodeDC `engine.workflow_l1` id.
- `engine.l2_run`, `engine.l2_session`, and current trace tables are useful evidence but are tech-debt-adjacent because they live in ENGINE-side OpsLayer.
- Do not turn ENGINE-side Agent Monitor/tender UI into core ontology roots.
- Procurement/tender concepts should later become a domain ontology package, not a core root.

## Future Interface Layer Guardrails

- Do not add new heavy custom product UI directly into ENGINE core.
- Future automation UI should live in a dedicated interface layer/service.
- ENGINE nodes may emit data/control bindings for that layer, but the layer owns views, widgets, dashboards, maps, forms, and control panels.
- Assistant-built interfaces must use ontology-backed meanings, not hardcoded one-off field guesses.
- Current tender/Agent Monitor UI is evidence of need and tech debt, not the target architecture.

## Assistant / MCP Routing Guardrails

- Assistant is not the same as Gateway identity.
- Codex, browser ChatGPT, MCP tool, local executor, and OPS Gateway are different execution surfaces.
- Ontology Core should help resolve target context before selecting grant/tool/workflow, especially for:
  - OPS user asks to inspect or switch an Engine workflow.
  - Engine user asks to create/update OPS cards.
  - Assistant needs to choose project/workflow/card context by human-readable name.
- Browser ChatGPT can propose RFCs, but source evidence and accepted docs remain on disk.

## Data Safety Guardrails

- Do not read or copy env files, secrets, database dumps, storage, runtime buffers, logs, caches, build outputs, `node_modules`, or archives into ontology docs.
- Do not delete files unless explicitly asked by the user.
- Do not edit application source code from the ontology workspace.
- Do not run Docker/build/install/test for docs-only ontology work.