kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Add Rule 53 for slot_fixes.yaml migration workflow

Browse source 
- Document that slot_fixes.yaml revision section is authoritative
- Add link_branch explanation for nested class attributes
- Clarify that deprecated slots must be fully removed, not just annotated
This commit is contained in:
kempersc 2026-01-14 19:57:08 +01:00
parent 13ba8fb09b
commit 9f9c69f7b8
2 changed files with 139 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

102
.opencode/rules/full-slot-migration-rule.md
View file

@ -31,10 +31,112 @@ The `slot_fixes.yaml` file has been **manually curated** to specify the exact re
- ✅ Follow the `revision` section TO THE LETTER
- ✅ Use EXACTLY the slots and classes specified
- ✅ Apply ALL components of the revision (both slots AND classes)
- ✅ Interpret `link_branch` fields correctly (see below)
- ✅ Update `processed.status: true` after completing migration
---
## Understanding `link_branch` in Revision Plans
🚨 **CRITICAL**: The `link_branch` field in revision plans indicates **nested class attributes**. Items with `link_branch: N` are slots/classes that belong TO the primary class, not standalone replacements.
### How to Interpret `link_branch`
| Revision Item | Meaning |
|---------------|---------|
| Items **WITHOUT** `link_branch` | **PRIMARY** slot and class to create |
| Items **WITH** `link_branch: 1` | First attribute branch that the primary class needs |
| Items **WITH** `link_branch: 2` | Second attribute branch that the primary class needs |
| Items **WITH** `link_branch: N` | Nth attribute branch for the primary class |
### Example: `visitor_count` Revision
```yaml
- original_slot_id: https://nde.nl/ontology/hc/slot/visitor_count
revision:
- label: has_or_had_quantity # PRIMARY SLOT (no link_branch)
type: slot
- label: Quantity # PRIMARY CLASS (no link_branch)
type: class
- label: has_or_had_measurement_unit # Quantity needs this slot
type: slot
link_branch: 1 # ← Branch 1: unit attribute
- label: MeasureUnit # Range of has_or_had_measurement_unit
type: class
value:
- visitors
link_branch: 1
- label: temporal_extent # Quantity needs this slot too
type: slot
link_branch: 2 # ← Branch 2: time attribute
- label: TimeSpan # Range of temporal_extent
type: class
link_branch: 2
```
**Interpretation**: This creates:
1. **Primary**: `has_or_had_quantity` slot → `Quantity` class
2. **Branch 1**: `Quantity.has_or_had_measurement_unit` → `MeasureUnit` (with value "visitors")
3. **Branch 2**: `Quantity.temporal_extent` → `TimeSpan`
### Resulting Class Structure
```yaml
# The Quantity class should have these slots:
Quantity:
slots:
- has_or_had_measurement_unit # From link_branch: 1
- temporal_extent # From link_branch: 2
```
### Complex Example: `visitor_conversion_rate`
```yaml
- original_slot_id: https://nde.nl/ontology/hc/slot/visitor_conversion_rate
revision:
- label: has_or_had_conversion_rate # PRIMARY SLOT
type: slot
- label: ConversionRate # PRIMARY CLASS
type: class
- label: has_or_had_type # ConversionRate.has_or_had_type
type: slot
link_branch: 1
- label: ConversionRateType # Abstract type class
type: class
link_branch: 1
- label: includes_or_included # ConversionRateType hierarchy slot
type: slot
link_branch: 1
- label: ConversionRateTypes # Concrete subclasses file
type: class
link_branch: 1
- label: temporal_extent # ConversionRate.temporal_extent
type: slot
link_branch: 2
- label: TimeSpan # Range of temporal_extent
type: class
link_branch: 2
```
**Interpretation**:
1. **Primary**: `has_or_had_conversion_rate` → `ConversionRate`
2. **Branch 1**: Type hierarchy with `ConversionRateType` (abstract) + `ConversionRateTypes` (concrete subclasses)
3. **Branch 2**: Temporal tracking via `temporal_extent` → `TimeSpan`
### Migration Checklist for `link_branch` Revisions
- [ ] Create/verify PRIMARY slot exists
- [ ] Create/verify PRIMARY class exists
- [ ] For EACH `link_branch: N`:
- [ ] Add the branch slot to PRIMARY class's `slots:` list
- [ ] Import the branch slot file
- [ ] Import the branch class file (if creating new class)
- [ ] Verify range of branch slot points to branch class
- [ ] Update consuming class to use PRIMARY slot (not deprecated slot)
- [ ] Update examples to show nested structure
---
## Mandatory: Follow slot_fixes.yaml Revisions Exactly
**The `revision` section in `slot_fixes.yaml` is AUTHORITATIVE.** Do not substitute different slots based on your own judgment.

37
AGENTS.md
View file

@ -1603,6 +1603,43 @@ The `revision` section in `slot_fixes.yaml` specifies the EXACT slots and classe
- ❌ Partially apply revisions
- ❌ Add deprecation notes (keeping both old and new)
**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 - `visitor_count` with `link_branch`**:
```yaml
- original_slot_id: https://nde.nl/ontology/hc/slot/visitor_count
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 # ← Branch 1
- label: MeasureUnit # Range of branch 1 slot
type: class
link_branch: 1
- label: temporal_extent # Quantity.temporal_extent
type: slot
link_branch: 2 # ← Branch 2
- label: TimeSpan # Range of branch 2 slot
type: class
link_branch: 2
```
**Interpretation**: Create `Quantity` class with TWO slots:
- `has_or_had_measurement_unit` → `MeasureUnit` (branch 1)
- `temporal_extent` → `TimeSpan` (branch 2)
**Example - Following slot_fixes.yaml**:
```yaml