theseus: add schema change protocol

- What: protocol for coordinating file format changes across agents
- Why: unanimous #1 priority from all 5 Engineering team members — schema
  changes without notification cause silent breakage
- Includes: producer/consumer map, backward compatibility rules, PR template,
  legacy alias documentation

Pentagon-Agent: Theseus <24DE7DA0-E4D5-4023-B1A2-3F736AFF4EEE>

ops/schema-change-protocol.md

@@ -0,0 +1,88 @@
+# 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).