glam/.opencode/rules/linkml/no-migration-deferral-rule.md

Rule 60: No Migration Deferral - Execute All slot_fixes.yaml Revisions

Status: MANDATORY

Summary

AI agents MUST execute ALL migrations specified in slot_fixes.yaml. The pattern of marking migrations as "WELL_STRUCTURED_NO_MIGRATION_NEEDED" or similar deferral notes is STRICTLY PROHIBITED except in the rarest cases of genuine semantic conflict.

The Problem

Previous AI agents incorrectly deferred >95% of slot_fixes.yaml migrations with notes like:

• "WELL_STRUCTURED_NO_MIGRATION_NEEDED"
• "Already has proper slot_uri"
• "Simple enum is appropriate"
• "Would add unnecessary indirection"
• "Current structure is adequate"

These deferrals were WRONG. The slot_fixes.yaml revisions were carefully curated based on:

• Ontology analysis (CIDOC-CRM, RiC-O, PROV-O, Schema.org alignment)
• Semantic correctness and consistency
• Pattern adherence (Rule 39: RiC-O naming, Rule 43: singular nouns)
• Type/Types class hierarchy design (Rule 0b)

The Rule

MANDATORY: Execute ALL Migrations

When encountering a slot_fixes.yaml entry with status: false:

1. READ the revision field - This specifies EXACTLY what to do
2. EXECUTE the migration - Create/update slots, classes, imports as specified
3. UPDATE status to true - Document what was done in notes

PROHIBITED: Deferral Reasoning

The following justifications are INVALID and NEVER acceptable:

Invalid Justification	Why It's Wrong
"Already has proper slot_uri"	slot_uri handles external mapping; internal structure is separate concern
"Simple string/enum is sufficient"	Consistency and extensibility trump local simplicity
"Would add unnecessary indirection"	Indirection enables reuse and future extension
"Creating a class would over-engineer"	Ontology design favors class-based modeling
"Current structure is well-designed"	Individual optimization conflicts with schema-wide patterns
"No semantic benefit"	Agent lacks context to make this judgment

VALID: Reasons to Pause (Not Defer)

The ONLY valid reasons to pause a migration (NOT defer indefinitely) are:

1. Semantic Conflict: The proposed revision contradicts the slot's documented semantic intent
2. Circular Dependency: Migration would create import cycle
3. External Consumer Impact: Breaking change affecting downstream systems
4. Class Already Exists: Target class exists under different name (document and merge)

When pausing: Add a feedback entry explaining the specific conflict and request human review. Do NOT mark as "NO_MIGRATION_NEEDED".

Decision Tree

Is there a slot_fixes.yaml entry with status: false?
├─ YES → Read the revision field
│        ├─ Does revision specify slots/classes to create?
│        │   └─ YES → EXECUTE THE MIGRATION (mandatory)
│        └─ Is there a genuine semantic conflict?
│            ├─ NO → EXECUTE THE MIGRATION (mandatory)
│            └─ YES → Document conflict in feedback, request human review
│                     (Do NOT mark as "no migration needed")
└─ NO → Nothing to do

Examples

WRONG: Deferral Note

- original_slot_id: https://nde.nl/ontology/hc/slot/example_slot
  revision:
    - label: has_or_had_example
      type: slot
    - label: Example
      type: class
  processed:
    status: true  # WRONG - marked true without doing work
    notes: "WELL_STRUCTURED_NO_MIGRATION_NEEDED - slot already has proper 
            slot_uri and the current structure is adequate"  # INVALID

CORRECT: Execute Migration

- original_slot_id: https://nde.nl/ontology/hc/slot/example_slot
  revision:
    - label: has_or_had_example
      type: slot
    - label: Example
      type: class
  processed:
    status: true
    timestamp: '2026-01-19T12:00:00Z'
    notes: 'Migrated 2026-01-19 per Rule 53/56.
      - Created has_or_had_example.yaml slot file
      - Created Example.yaml class file
      - Updated ClassA.yaml, ClassB.yaml to use new slot
      - Archived: modules/slots/archive/example_slot_archived_20260119.yaml'

CORRECT: Pause with Genuine Conflict

- original_slot_id: https://nde.nl/ontology/hc/slot/conflicting_slot
  revision:
    - label: has_or_had_foo
      type: slot
  processed:
    status: false  # Correctly left false
    notes: ''
  feedback:
    - timestamp: '2026-01-19T12:00:00Z'
      user: opencode-claude
      done: false
      comment: |
        PAUSED FOR HUMAN REVIEW - Genuine semantic conflict detected:
        - Revision specifies has_or_had_foo (temporal relationship)
        - But slot is used for immutable birth dates (should be has_*)
        - Request clarification on intended temporal semantics        

Statistics Context

The slot_fixes.yaml file contains 527 migration entries. Analysis of previous agent behavior:

• Incorrectly deferred: >95% of entries marked "NO_MIGRATION_NEEDED"
• Actually needing deferral: <5% (genuine semantic conflicts)
• Required action: Execute ALL migrations except those with documented semantic conflicts

Related Rules

• Rule 53: Full Slot Migration - slot_fixes.yaml is AUTHORITATIVE
• Rule 56: Semantic Consistency Over Simplicity - Always Execute Revisions
• Rule 57: slot_fixes.yaml Revision Key is IMMUTABLE
• Rule 58: Feedback vs Revision Distinction

Anti-Patterns Checklist

Before marking ANY migration as complete without execution, verify:

• Did I actually create the specified slots?
• Did I actually create the specified classes?
• Did I update all class files that use this slot?
• Did I archive the old slot file?
• Is my "notes" field documenting actual work done, not a deferral excuse?

If any answer is "no", the migration is NOT complete.

Consequences

Agents that defer migrations without genuine semantic conflict:

1. Create technical debt requiring human cleanup
2. Delay schema consistency improvements
3. Waste curator time reviewing false "completions"
4. Undermine trust in AI-assisted schema work

Execute the migrations. Do not defer.