# Schema Authority Documentation Checklist

**Date**: 2025-11-21  
**Task**: Establish LinkML schemas as single source of truth  
**Status**: ✅ COMPLETE

---

## Objectives

- [x] Add "Schema Source of Truth" documentation to agent instructions
- [x] Update schema references to new `schemas/20251121/linkml/` location
- [x] Document schema hierarchy (authoritative vs. derived)
- [x] Provide workflow for schema changes
- [x] Warn against editing auto-generated files

---

## Files Updated

### 1. `AGENTS.md` ✅
**Location**: Root directory  
**Status**: ✅ COMPLETE

- [x] Added Rule 0: LinkML Schemas Are the Single Source of Truth (line 24)
- [x] Documented master schema location: `schemas/20251121/linkml/`
- [x] Listed primary schema files (01_name_entity.yaml, 02_organization_observation_reconstruction.yaml)
- [x] Clarified derived files (RDF, TypeDB, UML, examples)
- [x] Documented regeneration workflow (edit LinkML → gen-owl → rdfpipe → validate)
- [x] Listed "Why LinkML is the Master" (5 reasons)
- [x] Documented NEVER/ALWAYS rules for agents
- [x] Added references to supporting docs (RDF_GENERATION_SUMMARY.md, etc.)

### 2. `.opencode/agent/README.md` ✅
**Location**: `.opencode/agent/` directory  
**Status**: ✅ COMPLETE

- [x] Added "🚨 Schema Source of Truth" section (lines 5-63)
- [x] Updated schema version from v0.2.0 to v0.2.1
- [x] Updated all schema references to `schemas/20251121/linkml/`
- [x] Updated agent schema mappings to new class names:
  - [x] `HeritageCustodian` → `CustodianAspect`
  - [x] `Location` → `PlaceAspect`
  - [x] `ChangeEvent` → `TemporalEvent`
  - [x] `Identifier` → (unchanged)
- [x] Updated validation commands with correct paths
- [x] Added schema features list (ISO 20275, multi-aspect modeling, etc.)
- [x] Updated footer metadata (version, date, schema location)

### 3. `SESSION_SUMMARY_20251121_SCHEMA_AUTHORITY_COMPLETE.md` ✅
**Location**: Root directory  
**Status**: ✅ COMPLETE

- [x] Documented session overview
- [x] Listed all changes made
- [x] Explained documentation hierarchy
- [x] Provided impact analysis
- [x] Created validation checklist
- [x] Listed next steps for future agents
- [x] Included technical context and statistics

### 4. `SCHEMA_AUTHORITY_CHECKLIST.md` ✅
**Location**: Root directory  
**Status**: ✅ COMPLETE (this file)

- [x] Created comprehensive task checklist
- [x] Documented completion status
- [x] Listed verification steps

---

## Content Verification

### Rule 0 in `AGENTS.md`

- [x] Positioned before existing Rule 1 (ontology consultation)
- [x] Clear heading: "Rule 0: LinkML Schemas Are the Single Source of Truth"
- [x] Master schema location documented
- [x] Primary schema files listed with descriptions
- [x] Derived/generated files clearly marked
- [x] Workflow for schema changes (5 steps)
- [x] "Why LinkML is the Master" section (5 bullet points)
- [x] NEVER rules (3 items)
- [x] ALWAYS rules (4 items)
- [x] References to supporting documentation

### Schema Source of Truth Section in `.opencode/agent/README.md`

- [x] Prominent warning emoji (🚨)
- [x] Master schema location (same as AGENTS.md)
- [x] Primary schema files (same as AGENTS.md)
- [x] Derived/generated files (same as AGENTS.md)
- [x] Workflow for schema changes (same as AGENTS.md)
- [x] "Why LinkML is the Master" (same as AGENTS.md)
- [x] NEVER rules (same as AGENTS.md)
- [x] ALWAYS rules (same as AGENTS.md)
- [x] References to supporting documentation (same as AGENTS.md)

### Schema Reference Updates

- [x] All old `schemas/` paths updated to `schemas/20251121/linkml/`
- [x] Schema version updated from v0.2.0 to v0.2.1
- [x] ISO 20275 migration mentioned
- [x] Class name mappings updated to reflect new schema
- [x] Validation commands use correct paths
- [x] Footer metadata reflects current state

---

## Consistency Check

### Between `AGENTS.md` and `.opencode/agent/README.md`

- [x] Master schema location identical
- [x] Primary schema files identical
- [x] Derived/generated files identical
- [x] Workflow steps identical
- [x] "Why LinkML is the Master" identical
- [x] NEVER rules identical
- [x] ALWAYS rules identical
- [x] Reference links identical

### Schema Authority Principles

- [x] LinkML is authoritative (not RDF, TypeDB, or UML)
- [x] Edit LinkML first, then regenerate derived formats
- [x] Never edit auto-generated files directly
- [x] Always validate changes with linkml-validate
- [x] Document schema changes in YAML comments
- [x] Use version control for schema tracking

---

## Integration with Existing Documentation

### References Added

- [x] `schemas/20251121/RDF_GENERATION_SUMMARY.md` - RDF generation process
- [x] `docs/MIGRATION_GUIDE.md` - Schema migration procedures
- [x] LinkML documentation: https://linkml.io/

### Related Documentation (Cross-Check)

- [x] `SESSION_SUMMARY_20251121_ISO20275_COMPLETE.md` - Migration completion
- [x] `MIGRATION_CHECKLIST_ISO20275.md` - Migration tasks
- [x] `schemas/20251121/uml/MERMAID_UPDATE_SUMMARY.md` - Diagram fixes
- [x] All references to schema authority are consistent

---

## Testing and Validation

### Manual Review

- [x] Read full text of `AGENTS.md` Rule 0
- [x] Read full text of `.opencode/agent/README.md` schema section
- [x] Verify all schema paths use `schemas/20251121/linkml/`
- [x] Verify no references to old `schemas/` directory
- [x] Verify version numbers are v0.2.1
- [x] Verify class name mappings are correct

### Agent Comprehension Test

- [x] Rule 0 is positioned prominently (before other rules)
- [x] Schema hierarchy is clearly explained
- [x] Workflow steps are numbered and sequential
- [x] Warnings are explicit (❌ DO NOT, ✅ ALWAYS)
- [x] Examples are provided where helpful
- [x] References link to supporting docs

### Future-Proofing

- [x] Documentation explains WHY LinkML is master (not just HOW)
- [x] Workflow is detailed enough for agents to follow
- [x] Common mistakes are explicitly warned against
- [x] Migration procedures are documented for future schema changes

---

## Completion Criteria

### Primary Objectives
- [x] Schema authority clearly established
- [x] LinkML designated as single source of truth
- [x] Derived file types clearly identified
- [x] Workflow documented for schema changes
- [x] Both agent instruction files updated

### Secondary Objectives
- [x] Consistency between `AGENTS.md` and `.opencode/agent/README.md`
- [x] All schema paths updated to new location
- [x] Schema version updated to v0.2.1
- [x] Class name mappings updated
- [x] Session documentation complete

### Quality Criteria
- [x] Clear and unambiguous language
- [x] Prominent placement (Rule 0, top of agent README)
- [x] Visual warnings (❌/✅ icons)
- [x] Numbered workflows for easy following
- [x] References to supporting documentation
- [x] Examples provided where helpful

---

## Sign-Off

**Task**: Schema Authority Documentation  
**Status**: ✅ COMPLETE  
**Date**: 2025-11-21  

**Files Modified**:
1. `AGENTS.md` (+58 lines)
2. `.opencode/agent/README.md` (+58 lines + scattered updates)
3. `SESSION_SUMMARY_20251121_SCHEMA_AUTHORITY_COMPLETE.md` (new, 400+ lines)
4. `SCHEMA_AUTHORITY_CHECKLIST.md` (new, this file)

**Total Documentation**: ~600 lines

**Verification**: All checklist items complete ✅

---

## Next Agent Handoff

Future agents working on this project should:

1. **Read Rule 0** in `AGENTS.md` before making any schema changes
2. **Refer to `schemas/20251121/linkml/`** for authoritative schema definitions
3. **Follow the workflow** (edit LinkML → regenerate RDF → update TypeDB → update UML → validate)
4. **Never edit** RDF, TypeDB, or UML files directly
5. **Always validate** changes with `linkml-validate`

**The schema authority is now clearly documented and ready for production use.**

---

**Prepared by**: OpenCode AI Agent  
**Session**: 2025-11-21 Schema Authority Documentation  
**Status**: ✅ ALL TASKS COMPLETE