KeiSeiKit-1.0/docs/TAXONOMY.md

TAXONOMY — Canonical Facet Vocabulary

Graph, not tree. Every primitive is a node; facets are orthogonal labels. Multi-faceted nodes are allowed (and expected). No facet is mandatory — the entire [taxonomy] and [lineage] sections are OPTIONAL on every manifest shape (capability.toml, _manifests/**/*.toml, _roles/*.toml, atom markdown frontmatter).

---

Why facets, not a tree

A classical rooted tree (e.g. "capability → gate → policy → no-git-ops") forces an arbitrary primary axis. Real primitives live in several axes at once: no-git-ops is a capability (kingdom), a gate (mechanism), a policy (domain), targets the agent-substrate (layer), is stable, and ships as a rust module. A tree makes five of those six second-class.

Facets let a catalog query along any axis independently:

• "all gate mechanisms" — security review surface
• "all verify mechanisms" — quality/CI surface
• "all policy-domain primitives" — rule-coverage surface
• "all experimental stability" — risk review
• "all rust language" — build-graph

No primitive needs to choose a primary axis. Multiple facets coexist.

---

Facets

kingdom — What kind of thing is this?

kingdom = capability | atom | skill | block | runtime | schema | role | manifest

• capability — agent-substrate capability (gate / verify / transform)
• atom — substrate atom (command / query / stream / transform)
• skill — user-invocable skill (/skill-name)
• block — composable prompt-block
• runtime — runtime module consuming atoms/capabilities
• schema — JSON schema referenced by atom I/O
• role — agent-role manifest (_roles/*.toml)
• manifest — assembled agent manifest (_manifests/**/*.toml)

mechanism — How does it act?

mechanism = gate | verify | transform | store | compose | fetch | analyze | router | cache

• gate — PreToolUse-style deny decision (e.g. no-git-ops, bash-allowlist)
• verify — post-condition check (e.g. cargo-check-green)
• transform — pure value-in/value-out (no side-effects)
• store — persisted state (SQLite, filesystem, ledger)
• compose — assembles other primitives (manifests, pipes)
• fetch — retrieves external data (provider, api)
• analyze — inspects input, emits report
• router — dispatches based on classification
• cache — memoizes pure invocations

domain — What subject-matter area?

domain = policy | quality | scope | safety | output | tools | research | content | social | task | sage

• policy — RULE 0.x enforcement / compliance gates
• quality — cargo-check, tests-green, constructor-pattern
• scope — write-whitelist, file-denylist, path-guards
• safety — secret scanning, citation verification
• output — response shape, formatter, report-gen
• tools — tool allowlists, bash patterns, deny-tools
• research — research agents, search-core, fetch primitives
• content — content-store, content-normalizer
• social — social-store, social-normalizer
• task — task primitives (kei-task)
• sage — higher-level reasoning / kei-sage primitives

layer — Which substrate does it live in?

layer = atom-substrate | agent-substrate | cross | tooling

• atom-substrate — substrate for callable atoms (kei-runtime, kei-pipe)
• agent-substrate — substrate for agent manifests (capabilities, roles)
• cross — spans both (shared discovery, schemas)
• tooling — pure developer tooling (kei-forge, validators)

stage — When is it active?

stage = runtime | design-time | ephemeral

• runtime — executes during agent turns
• design-time — consumed at assembly / scaffold time
• ephemeral — one-shot (migration, provision, smoke)

stability — Maturity

stability = experimental | beta | stable | deprecated

Standard semver-style ladder. deprecated primitives must name a successor in [lineage] or their text.md.

language — Implementation medium

language = rust | shell | md | toml | json | jsonschema

• rust — primary implementation in a Rust crate
• shell — bash / posix script
• md — markdown (atoms, capability text, documentation)
• toml — config-only (capability manifest, role manifest)
• json / jsonschema — data / schema definitions

Multiple languages can apply (e.g. atom markdown with a JSON schema attached and a Rust runtime) — but the language facet names the PRIMARY medium of the node being described.

---

[lineage] — Graph edges, not tree edges

parents = ["[[ancestor-one]]", "[[ancestor-two]]"]   # wikilinks to predecessors
creator = "ag-orchestrator-human"                    # DNA id or human slug
created = "2026-04-23"                               # ISO-8601 date
fork_from = "dna-abc123..."                          # parent DNA if forked

• parents — wikilinks ([[slug]]) to primitives this one extends or composes. Multiple parents allowed (diamond lineage). A primitive with no parents is a root of its sub-graph.
• creator — identity responsible for the primitive's existence. For human-authored nodes: ag-orchestrator-human or a slug. For agent- authored: the agent's DNA id.
• created — ISO-8601 date (YYYY-MM-DD). When the manifest was first authored, not when it was last edited.
• fork_from — if this primitive was forked from another (DNA id), record the source here so the graph shows the edge.

---

Example — fully-faceted capability manifest

[capability]
name = "policy::no-git-ops"
category = "policy"
version = "1.0"
description = "..."
rationale = "..."

[restricts]
tool-patterns = ['^git( |$)', '^gh repo']

[parameterized]
accepts = []

[text]
path = "text.md"

[gate]
rust-module = "gates::policy_no_git_ops"
event = "PreToolUse:Bash"
severity = "block"

# Optional — all fields optional individually too.
[taxonomy]
kingdom = "capability"
mechanism = "gate"
domain = "policy"
layer = "agent-substrate"
stability = "stable"
language = "rust"

[lineage]
parents = []
creator = "ag-orchestrator-human"
created = "2026-04-23"

---

Non-breaking contract

• Every field in [taxonomy] and [lineage] is OPTIONAL.
• The entire [taxonomy] and [lineage] sections are OPTIONAL.
• Manifests without either section parse exactly as before (backward-compat guaranteed by taxonomy_smoke.rs tests in kei-atom-discovery).
• New primitives SHOULD include at least kingdom + mechanism + domain.
• The facet vocabularies are additive — new values can be appended without breaking existing consumers. Unknown values pass through as strings.

---

Rule lock

2026-04-23. Vocabularies live in this file; any new allowed value lands here first. Runtime consumers (kei-atom-discovery, kei-sage, kei-runtime) MUST treat unknown values as strings (never crash on new vocabulary).