feat(migration): auto-migration rename detection

[bpamiri]

Summary

Closes item 6 ("Migration rename detection") from docs/wheels-vs-frameworks.md "Where Wheels Trails" list — promoting it to "Where Wheels Leads" as item 16.

AutoMigrator.diff() now detects column renames via two complementary mechanisms:

• Explicit hints — options.renames = {"oldCol": "newCol"} is authoritative. Invalid hints raise typed exceptions (Wheels.InvalidRenameHint, Wheels.RenameHintTypeMismatch, Wheels.DuplicateRenameHint).
• Heuristic suggestions — normalized-token match + Levenshtein scoring. Unambiguous score-1.0 pairs auto-confirm as renames (e.g., full_name ↔ fullName); everything else surfaces as suggestedRenames requiring explicit confirmation. Ambiguity is pre-counted across the full candidate pool before greedy assignment, so ambiguous score-1.0 pairs are correctly demoted to suggestions rather than silently applied.

What's included

• Core engine: new vendor/wheels/migrator/RenameDetector.cfc (pure logic, no DB/model deps, 275 lines, 39 unit specs)
• AutoMigrator integration: diff(modelName, options) and diffAll(options) accept hints and threshold; generateMigrationCFC() emits renameColumn() in up() (first) and reversed renameColumn() in down() (last). Backward compatible — zero breaking changes.
• CLI: new wheels dbmigrate diff [modelName] command with --rename=OLD:NEW, --threshold, --write, --name flags. For diffAll, use --rename=User.old_col:newCol.
• MCP: wheels_migrate(action="diff") handler; returns full JSON envelope with renameColumns, suggestedRenames, addColumns, removeColumns, changeColumns.
• Docs: moved item 6 from Trails → Leads in wheels-vs-frameworks.md, new dbmigrate-diff.md CLI reference, auto-migration sections in migrations.md CLI guide and the migrations tutorial README.md, CLAUDE.md quick reference.

Spec & plan

• Spec: docs/superpowers/specs/2026-04-15-auto-migration-rename-detection-design.md
• Plan: docs/superpowers/plans/2026-04-15-auto-migration-rename-detection.md

Stats

• 23 commits, 12 files changed, +1548/-14 lines
• 49 new test specs (39 RenameDetector + 10 AutoMigrator integration)
• Full suite on Lucee 7 + SQLite: 2948 pass / 0 fail / 0 error

Intentional behavioral change

A model rename that previously produced removeColumn + addColumn (with data loss) will now produce renameColumn when the heuristic confirms it at score 1.0 unambiguously (e.g., case/underscore variants of the same tokens). This is the desired fix; noted here so anyone regenerating migrations is aware.

Test Plan

• Full Lucee 7 + SQLite test suite: 2948 pass / 0 fail / 0 error
• Manual CLI bridge smoke test (command=diff for both single-model and diffAll)
• Manual MCP smoke test (wheels_migrate action="diff")
• Adobe CF 2023 bridge smoke test — success: true confirms code loads and executes on Adobe flavor
• Adobe CF 2025 full test suite — deferred. The container has a pre-existing graphqlclient package gap that blocks the suite runner. Not introduced by this branch. Recommend fixing that container setup separately and then running: docker compose up -d adobe2025 && curl -s "http://localhost:62025/wheels/core/tests?db=sqlite&format=json&directory=wheels.tests.specs.migrator"
• Cross-database matrix — tested on SQLite only. Worth an Actions run on MySQL/PostgreSQL/MSSQL before merge.
• MCP tool schema follow-up — the migrate tool's declared argument list only lists action; diff-specific params (modelName, hints, heuristicThreshold, write) are not in the schema. They work because we dispatch internally, but AI agents can't discover them from tool introspection. Fast-follow PR suggested.

🤖 Generated with Claude Code