docs: add version upgrade guidance to swamp-extension-model skill

[stack72]

docs: add version upgrade guidance to swamp-extension-model skill

Summary

The swamp-extension-model skill had no documentation about the upgrades field on model definitions. This meant that when a model's version was bumped, existing instantiated models would be left stuck at their old typeVersion with no migration path — users (and Claude) had no idea they needed to add upgrade entries.

What changed

• skill.md: Added upgrades row to the Model Structure table, a new "Version Upgrades" section with a user prompt workflow, Key Rule 9 requiring upgrades when bumping version, and a reference link
• references/upgrades.md (new): Detailed reference covering the user prompt workflow, how lazy upgrades work, common patterns (no-op, add field, rename, remove), multi-step chain example, rules, and consequences of skipping upgrades
• references/examples.md: Added a complete "Model with Version Upgrades" example showing a notifier model evolving through three versions
• design/models.md: Fixed upgradeGlobalArguments → upgradeAttributes to match the actual code interface (VersionUpgrade in model.ts and UserUpgradeSchema in user_model_loader.ts)

Impact

The key behavioral change is that Claude is now instructed to prompt the user about schema changes when bumping a version, rather than guessing or silently skipping the upgrade. This ensures existing model instances get proper migration entries.

Why this is correct

• The upgradeAttributes function name matches what the code validates (user_model_loader.ts:106 and model.ts:558)
• The upgrade chain mechanics match DefinitionUpgradeService behavior (lazy execution at method run time, filtered by toVersion > typeVersion, persisted after first run)
• Examples follow skill conventions (no type annotations in execute parameters, snake_case file naming)
• skill.md stays under 560 lines (553), following skill-creator progressive disclosure guidelines — detailed content lives in the reference file

🤖 Generated with Claude Code

[github-actions]

Code Review

Blocking Issues

None.

Suggestions

1. Inconsistent type prefix in upgrades.md example: In references/upgrades.md line 107, the multi-step upgrade chain example uses type: "acme/notifier" (missing the @ prefix), while the same model in references/examples.md correctly uses type: "@acme/notifier". The SKILL.md convention specifies @collective/name format. Consider changing to type: "@acme/notifier" for consistency.

Overall this is a well-structured documentation addition. The upgradeAttributes naming matches the actual code (model.ts:560, user_model_loader.ts:106), the fix to design/models.md corrects a real naming mismatch, and the progressive disclosure approach (summary in SKILL.md, details in reference file) follows skill-creator guidelines.