18 added, 9 removed. Audit B to B.
---
name: "wow-migrate"
- description: "Audit, plan, implement, debug, review, and verify breaking application migrations to a pinned Wow release, including cross-major compatibility, known same-major source or configuration breaks, and storage-format or data cutovers even when both versions are v8. Use only when service migration, data reconciliation, cutover, rollout, or rollback is the primary outcome. Do not use for first-time adoption, routine same-major service upgrades with no known breaking contract and no data migration, framework release preparation or version metadata, repository tooling, or ordinary development, review, and failures."
+ description: "Handle downstream cross-major or otherwise breaking Wow migrations across pinned releases, Wow application source/configuration/generated/runtime contracts, or Wow-managed storage/data. First adoption without history conversion belongs to wow-develop; history conversion, reconciliation, cutover, or incompatible-write rollback belongs here. Exclude the Wow framework repository, generic migrations, routine same-major non-breaking upgrades, and ordinary development/review/failures."
---
# Migrate Wow Across Breaking Boundaries
+ ## Scope gate
+
+ Use only for a downstream application; the Wow framework repository and its modules never qualify. Require scoped source/target to use or introduce Wow plus a cross-major upgrade, known source/configuration/generated/runtime break, or Wow-managed storage/data change. Routine same-major non-breaking upgrades and first adoption stay with `wow-develop` unless adoption requires Wow-managed history/compatibility conversion, data reconciliation/cutover, or rollback after incompatible target writes. Checkout-wide markers and unrelated application contracts do not qualify. Otherwise state that this Skill does not apply and stop using it.
+
Own the complete migration task. Treat breaking release upgrades—including cross-major and same-major source/config contract changes—and storage/data cutovers as platform, source, generated-contract, data, runtime, and release migrations rather than dependency bumps.
## Contract
- Pin the exact source and target versions before implementation. “v8” alone is not an executable target.
- Use the target tag's source, tests, BOM, release notes, and generated contracts as authority.
- Distinguish audit, planning, code implementation, data rehearsal, production cutover, and review modes.
- Treat code-write authorization, data-write authorization, and production-release authorization as separate scopes.
- Mark missing production, data, or deployment evidence as `MISSING EVIDENCE`.
- Never claim migration completion from dependency resolution, compilation, startup, or a smoke test alone.
+ - Keep separate evidence gates for compile/test/build, resolved dependencies, `runtimeClasspath`, application startup, real HTTP requests, external integration/data validation, deployability, and production readiness. A passing gate never proves a later gate.
## Access matrix
- A target checkout explicitly placed in scope authorizes read-only inspection of source, tests, generated artifacts, and checked-in non-secret configuration.
- - Do not read `.env` files, credentials, tokens, private keys, secret-manager values, or decrypted configuration without explicit authorization and a demonstrated need. Prefer names, schemas, and redacted metadata.
+ - Do not read `.env` files, credentials, tokens, private keys, secret-manager values, or decrypted configuration without explicit authorization and a demonstrated need. Never print full configuration files or secret values; inspect key names, schemas, and redacted metadata, and recommend rotation when plaintext credentials are discovered.
- Production metadata, logs, deployment state, and application data each require an exact environment/target plus explicit read authorization; one does not imply another.
- Local/code writes, non-production data writes, production data writes, traffic changes, and releases are separate authorizations. Never infer a broader scope from a narrower one.
- Record every inaccessible scope as `MISSING EVIDENCE`; do not bypass it with another credential, environment, or copied data source.
## Workflow
- Execute only the stages required by the requested mode and explicitly authorized scope. Audit, planning, review, and diagnosis remain read-only unless a code fix is requested. `Adapt` requires code-write authorization. Data rehearsal and every write performed by `Validate` require an exact isolated target plus explicit non-production data-write authorization. Cutover, traffic changes, production data writes, and release each require their own explicit production authorization. Skip data conversion when target-specific evidence proves no conversion or rebuild is needed.
+ Execute only the stages required by the requested mode and explicitly authorized scope. Audit, planning, review, and diagnosis remain read-only unless a code fix is requested. `Adapt` requires code-write authorization. `Rehearse data` and every write performed by `Validate integrations and data` require an exact isolated target plus explicit non-production data-write authorization. Cutover, traffic changes, production data writes, and release each require their own explicit production authorization. Skip data conversion when target-specific evidence proves no conversion or rebuild is needed.
1. **Baseline**: resolve current Wow, Spring Boot, Kotlin/KSP, Java, storage, messaging, runtime customization, generated contracts, and deployment topology.
2. **Target**: pin the exact target release and verify its platform and storage contracts from that tag.
3. **Matrix**: classify every dependency, source API, generated artifact, configuration, runtime owner, store, and release gate.
4. **Adapt**: change platform and source in dependency order; regenerate contracts from their source.
- 5. **Rehearse data**: inventory source and target, back up, dry-run, checksum, reconcile, and prove resume/idempotency in isolation.
- 6. **Validate**: only with the isolated-target and data-write authorization above, start one target-version instance and verify write, idempotency, replay, query, regeneration, monitoring, and graceful shutdown.
- 7. **Cut over**: stop and drain all source-version writers, migrate offline, reconcile, switch traffic, then scale only the target version.
- 8. **Observe and roll back**: monitor agreed signals and preserve distinct rollback paths for zero and non-zero target-version production writes.
+ 5. **Prove runtime and transport**: inspect the resolved runtime graph and `runtimeClasspath`, perform an isolated startup, exercise the application's actual HTTP or messaging surface, and stop gracefully using `references/runtime-rest-validation.md`. Keep original and temporary-isolation results separate.
+ 6. **Rehearse data**: only with an exact isolated target and data-write authorization, inventory source and target, back up, dry-run, checksum, reconcile, and prove resume/idempotency.
+ 7. **Validate integrations and data**: with separately authorized targets, verify write, idempotency, replay, query, regeneration, external integrations, monitoring, and shutdown; otherwise record `MISSING EVIDENCE`.
+ 8. **Cut over**: stop and drain all source-version writers, migrate offline, reconcile, switch traffic, then scale only the target version.
+ 9. **Observe and roll back**: monitor agreed signals and preserve distinct rollback paths for zero and non-zero target-version production writes.
## Load by risk
| Scope | Load |
|---|---|
| Platform, source, generated metadata, runtime or custom store audit | `references/migration-risk-map.md` |
+ | Runtime dependency, isolated startup, HTTP/REST or actual transport, and shutdown validation | `references/runtime-rest-validation.md` |
| Data inventory, rehearsal, cutover, reconciliation or rollback | `references/cutover-evidence.md` |
- | Static discovery of v6 exposure | Read `scripts/audit-v6-usage.sh`, run it with `--help`, then execute it against the target checkout |
+ | Static discovery of v6 exposure | Read `scripts/audit-v6-usage.sh`, run it with `--help`, then execute it with the explicit target application/module root—not a monorepo default |
| Migration plan or status report | Copy `assets/migration-matrix.md` and fill only evidence-backed fields |
The audit script reports leads, not incompatibility proof or completeness. Verify every match against the pinned target tag.
## Hard safety gates
- Do not write application data without explicit environment and scope authorization.
+ - Do not call external business APIs without explicit target and authorization. Prefer read-only local probes; mark blocked external or data validation as `MISSING EVIDENCE`.
+ - Keep isolation-only arguments, profiles, configuration, and dependency experiments out of the committed migration unless independently justified as the permanent fix.
- Verify recoverable backups, exact targets, inventory, stop conditions, dry-run, resume, checksum, and failure-closed behavior before migration writes.
- Do not run old and new writers together unless the pinned target contract explicitly provides and verifies a mixed-version protocol.
- Do not use broad deletion, ownership-marker edits, or configuration suppression to hide conflicts.
- Do not claim production readiness without rollback rehearsal and reconciliation evidence.
## Completion
- Report the baseline and pinned target, migration matrix status, changed files and contracts, executed verification, data/cutover/rollback state, and every `MISSING EVIDENCE` item. Separate completed code work from unexecuted environment operations.
+ Report the baseline and pinned target, changed files/contracts, original startup result, every temporary isolation argument or dependency, runtime classpath gaps, applicable HTTP or transport evidence, REST binding regressions, external/data/cutover/rollback state, and every `MISSING EVIDENCE` item. State separately whether migration code is complete, local runtime passed, the artifact is deployable, and production readiness is proved; none implies the next.