glam/.opencode/rules/slot-fixes-revision-immutability-rule.md

# Rule: slot_fixes.yaml Revision Key Immutability

## Status: CRITICAL

## Summary

The `revision` key in `slot_fixes.yaml` is **IMMUTABLE**. AI agents MUST follow revision specifications exactly and are NEVER permitted to modify the content of revision entries.

## The Authoritative Source

The file `slot_fixes.yaml` serves as the **curated migration specification** for all slot consolidations in the Heritage Custodian Ontology. Each entry's `revision` section was manually curated based on:

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

## What Agents CAN Do

| Action | Permitted | Location |
|--------|-----------|----------|
| Add completion notes | ✅ YES | `processed.notes` |
| Update status | ✅ YES | `processed.status` |
| Add feedback responses | ✅ YES | `feedback.response` |
| Mark feedback as done | ✅ YES | `feedback.done` |
| Execute the migration per revision | ✅ YES | Class/slot files |

## What Agents CANNOT Do

| Action | Permitted | Reason |
|--------|-----------|--------|
| Modify `revision` content | ❌ NEVER | Authoritative specification |
| Substitute different slots | ❌ NEVER | Violates curated design |
| Skip revision components | ❌ NEVER | Incomplete migration |
| Add new revision items | ❌ NEVER | Requires human curation |
| Change revision labels | ❌ NEVER | Breaks semantic mapping |
| Reorder revision items | ❌ NEVER | `link_branch` dependencies |

## Structure of slot_fixes.yaml Entries

```yaml
- original_slot_id: https://nde.nl/ontology/hc/slot/example_slot
  original_slot_label: example_slot
  revision:                          # ← IMMUTABLE - DO NOT MODIFY
    - label: has_or_had_example      # Generic slot to use
      type: slot
    - label: Example                 # Class for range
      type: class
    - label: has_or_had_attribute    # Nested attribute (link_branch: 1)
      type: slot
      link_branch: 1
  processed:
    status: false                    # ← CAN UPDATE to true
    notes: ""                        # ← CAN ADD notes here
  feedback:                          # ← CAN ADD responses here
    user: "Simon C. Kemper"
    date: "2026-01-17"
    message: "Migration incomplete"
    done: false                      # ← CAN UPDATE to true
    response: ""                     # ← CAN ADD response here
```

## Understanding `link_branch` in Revisions

The `link_branch` field indicates **nested class attributes**:

| Revision Item | Meaning |
|---------------|---------|
| Items **WITHOUT** `link_branch` | PRIMARY slot and class to create |
| Items **WITH** `link_branch: 1` | First attribute the primary class needs |
| Items **WITH** `link_branch: 2` | Second attribute the primary class needs |

**Example**:
```yaml
revision:
  - label: has_or_had_quantity     # PRIMARY SLOT
    type: slot
  - label: Quantity                 # PRIMARY CLASS
    type: class
  - label: has_or_had_measurement_unit   # Quantity.has_or_had_measurement_unit
    type: slot
    link_branch: 1
  - label: MeasureUnit              # Range of branch 1 slot
    type: class
    link_branch: 1
```

## Migration Workflow

1. **READ** the `revision` section completely
2. **VERIFY** all referenced slots/classes exist (or create them)
3. **REMOVE** old slot from imports, slots list, and slot_usage in consuming classes
4. **ADD** new slot(s) and class import(s) per revision specification
5. **UPDATE** slot_usage to narrow range to specified class
6. **VALIDATE** with `linkml-lint` or `gen-owl`
7. **UPDATE** slot_fixes.yaml:
   - Set `processed.status: true`
   - Add completion note to `processed.notes`
   - If feedback exists, set `feedback.done: true` and add `feedback.response`

## Anti-Patterns

### WRONG - Modifying Revision Content

```yaml
# Agent incorrectly "improves" the revision
revision:
  - label: has_description          # ❌ CHANGED from has_or_had_description
    type: slot
  - label: TextDescription          # ❌ CHANGED from Description
    type: class
```

### WRONG - Substituting Different Slots

```yaml
# Agent uses a different slot than specified
# Revision says: has_or_had_type + BindingType
# Agent uses: binding_classification + BindingClassification  ❌ WRONG
```

### WRONG - Partial Migration

```yaml
# Agent only creates the slot, ignores the class
revision:
  - label: has_or_had_type    # ✅ Agent created this
    type: slot
  - label: BindingType        # ❌ Agent ignored this
    type: class
```

### CORRECT - Following Revision Exactly

```yaml
# Revision specifies:
revision:
  - label: has_or_had_description
    type: slot
  - label: Description
    type: class

# Agent creates/uses EXACTLY:
# 1. Import ../slots/has_or_had_description
# 2. Import ../classes/Description  
# 3. slot_usage: has_or_had_description with range: Description
```

## Rationale

1. **Curated Quality**: Revisions were manually designed with ontology expertise
2. **Consistency**: Same patterns applied across all migrations
3. **Auditability**: Clear record of intended vs. actual changes
4. **Reversibility**: Original specifications preserved for review
5. **Trust**: Users can rely on revision specifications being stable

## Related Rules

- **Rule 53**: Full Slot Migration - slot_fixes.yaml is AUTHORITATIVE
- **Rule 56**: Semantic Consistency Over Simplicity
- **Rule 39**: Slot Naming Convention (RiC-O Style)
- **Rule 38**: Slot Centralization and Semantic URI Requirements
- **Rule 0b**: Type/Types File Naming Convention

## See Also

- `schemas/20251121/linkml/modules/slots/slot_fixes.yaml` - The authoritative file
- `.opencode/rules/full-slot-migration-rule.md` - Migration execution rules
- `.opencode/rules/semantic-consistency-over-simplicity.md` - Why revisions must be followed