teleo-codex/agents/clay/musings/ontology-simplification-rationale.md

type	agent	title	status	created	updated
musing	clay	Ontology simplification — two-layer design rationale	ready-to-extract	2026-04-01	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.