---
type: musing
agent: clay
title: "Ontology simplification — two-layer design rationale"
status: ready-to-extract
created: 2026-04-01
updated: 2026-04-01
---

# Why Two Layers: Contributor-Facing vs Agent-Internal

## The Problem

The codex has 11 schema types: attribution, belief, claim, contributor, conviction, divergence, entity, musing, position, sector, source. A new contributor encounters all 11 and must understand their relationships before contributing anything.

This is backwards. The contributor's first question is "what can I do?" not "what does the system contain?"

From the ontology audit (2026-03-26): Cory flagged that 11 concepts is too many. Entities and sectors generate zero CI. Musings, beliefs, positions, and convictions are agent-internal. A contributor touches at most 3 of the 11.

## The Design

**Contributor-facing layer: 3 concepts**

1. **Claims** — what you know (assertions with evidence)
2. **Challenges** — what you dispute (counter-evidence against existing claims)
3. **Connections** — how things link (cross-domain synthesis)

These three map to the highest-weighted contribution roles:
- Claims → Extractor (0.05) + Sourcer (0.15) = 0.20
- Challenges → Challenger (0.35)
- Connections → Synthesizer (0.25)

The remaining 0.20 (Reviewer) is earned through track record, not a contributor action.

**Agent-internal layer: 11 concepts (unchanged)**

All existing schemas remain. Agents use beliefs, positions, entities, sectors, musings, convictions, attributions, and divergences as before. These are operational infrastructure — they help agents do their jobs.

The key design principle: **contributors interact with the knowledge, agents manage the knowledge**. A contributor doesn't need to know what a "musing" is to challenge a claim.

## Challenge as First-Class Schema

The biggest gap in the current ontology: challenges have no schema. They exist as a `challenged_by: []` field on claims — unstructured strings with no evidence chain, no outcome tracking, no attribution.

This contradicts the contribution architecture, which weights Challenger at 0.35 (highest). The most valuable contribution type has the least structural support.

The new `schemas/challenge.md` gives challenges:
- A target claim (what's being challenged)
- A challenge type (refutation, boundary, reframe, evidence-gap)
- An outcome (open, accepted, rejected, refined)
- Their own evidence section
- Cascade impact analysis
- Full attribution

This means: every challenge gets a written response. Every challenge has an outcome. Every successful challenge earns trackable CI credit. The incentive structure and the schema now align.

## Structural Importance Score

The second gap: no way to measure which claims matter most. A claim with 12 inbound references and 3 active challenges is more load-bearing than a claim with 0 references and 0 challenges. But both look the same in the schema.

The `importance` field (0.0-1.0) is computed from:
- Inbound references (how many other claims depend on this one)
- Active challenges (contested claims are high-value investigation targets)
- Belief dependencies (how many agent beliefs cite this claim)
- Position dependencies (how many public positions trace through this claim)

This feeds into CI: challenging an important claim earns more than challenging a trivial one. The pipeline computes importance; agents and contributors don't set it manually.

## What This Doesn't Change

- No existing schema is removed or renamed
- No existing claims need modification (the `challenged_by` field is preserved during migration)
- Agent workflows are unchanged — they still use all 11 concepts
- The epistemology doc's four-layer model (evidence → claims → beliefs → positions) is unchanged
- Contribution weights are unchanged

## Migration Path

1. New challenges are filed as first-class objects (`type: challenge`)
2. Existing `challenged_by` strings are gradually converted to challenge objects
3. `importance` field is computed by pipeline and backfilled on existing claims
4. Contributor-facing documentation (`core/contributor-guide.md`) replaces the need for contributors to read individual schemas
5. No breaking changes — all existing tooling continues to work

## Connection to Product Vision

The Game (Cory's framing): "You vs. the current KB. Earn credit proportional to importance."

The two-layer ontology makes this concrete:
- The contributor sees 3 moves: claim, challenge, connect
- Credit is proportional to difficulty (challenge > connection > claim)
- Importance score means challenging load-bearing claims earns more than challenging peripheral ones
- The contributor doesn't need to understand beliefs, positions, entities, sectors, or any agent-internal concept

"Prove us wrong" requires exactly one schema that doesn't exist yet: `challenge.md`. This PR creates it.
