glam/.opencode/rules/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

```yaml
- 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

```yaml
- 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

```yaml
- 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.**