teleo-codex/ops/schema-change-protocol.md

Schema Change Protocol

When any agent changes a file format that other agents read or write, those agents need to know before their next session. This protocol prevents silent breakage.

The Rule

Any PR that changes a schema must:

1. Update the schema spec in schemas/ to reflect the new format
2. Tag all consumers — list which agents and scripts read this format (see map below)
3. Include a migration note — what happens to existing files? (backfill on edit, ignore old files, or batch migration)
4. State backward compatibility — can old-format files still be parsed? If not, the PR must include the migration

What Counts as a Schema Change

Change Type	Example	Requires Protocol?
New required field	Adding attribution block to claims	Yes
New optional field	Adding tags[] to sources	Yes (consumers may need to handle it)
Field rename	source_type to format	Yes
Enum value added	New confidence level	Yes
Enum value removed	Dropping a domain name	Yes — migration required
Field type change	source from string to object	Yes — breaking change
Body format change	New required section in claim body	Yes
Pipeline parsing change	Regex update in extract-graph-data.py	Yes

Not a schema change: Adding a new claim, entity, or source file that follows the existing format. Normal PR workflow applies.

Producer/Consumer Map

Format	Schema	Producers	Consumers	Pipeline
Claim	schemas/claim.md	All proposers (Rio, Clay, Theseus, Vida, Astra)	Leo (eval), all agents (beliefs), visitors	extract-graph-data.py
Source	schemas/source.md	All proposers, Epimetheus (pipeline)	Proposers (extraction), Epimetheus (pipeline)	extract-cron.sh
Entity	schemas/entity.md	Domain agents	All agents (references), visitors	extract-graph-data.py
Belief	schemas/belief.md	Each agent (own file)	Leo (review), other agents (cross-ref)	None currently
Position	schemas/position.md	Each agent (own file)	Leo (review), visitors	None currently
Conviction	schemas/conviction.md	Cory only	All agents, visitors	extract-graph-data.py
Divergence	schemas/divergence.md	Any agent	All agents, visitors	None currently
Musing	schemas/musing.md	Each agent (own folder)	That agent only	None
Sector	schemas/sector.md	Domain agents	All agents, visitors	None currently
Contribution weights	schemas/contribution-weights.yaml	Cory / Leo	contributors.json build	Build script
Graph data	(derived)	extract-graph-data.py	Frontend, system prompts	Auto-generated

How to Tag Consumers

In the PR body, add a section:

## Schema Change

**Format affected:** claim
**Change:** added optional `attribution` block
**Backward compatible:** yes — old claims without attribution still parse
**Migration:** backfill on next edit (no batch migration needed)
**Consumers to notify:** Leo, Rio, Clay, Theseus, Vida, Astra, extract-graph-data.py

If the change affects extract-graph-data.py or any other pipeline script, the PR must update that script too — don't merge a schema change that breaks the build.

Backward Compatibility Rules

1. New optional fields — always backward compatible. Add to schema spec, document default behavior when absent. No migration needed.
2. New required fields — must include migration. Either batch-update all existing files in the same PR, or make the field optional first and required later after backfill.
3. Field renames — keep old name as accepted alias in pipeline scripts. Document deprecation. Remove old name only after all files are updated.
4. Enum additions — backward compatible. Add to schema spec.
5. Enum removals — breaking. Must migrate all files using the removed value in the same PR.
6. Type changes — breaking. Must migrate all affected files in the same PR.

Legacy Aliases (Currently Active)

These old field names are still accepted by the pipeline. Don't use them in new files, but don't break them in existing files either:

Old Name	Current Name	Format
evidence	source	source.md
archive	(removed)	source.md
source_type	format	source.md
date_published	date	source.md

Version Tracking

No formal version numbers. Schema changes are tracked by:

• The PR that made the change (searchable in git history)
• The updated schema spec in schemas/
• The commit message, which should reference the schema change explicitly

If the system grows to need formal versioning, add a schema_version field to frontmatter. Not needed at current scale (~500 claims, 6 agents).