# Migration checklist — {{PROJECT_NAME}}

Per-project checklist for migrating `{{PROJECT_PATH}}` from legacy Linux CMake / Windows `.vcxproj` to unified CMake + Conan + presets.

**Shared policy:** `tools/ai-rules/docs/legacy-superbuild-migration.md`
**Status doc:** `docs/migration/projects/{{PROJECT_SLUG}}.md`
**Owner:** {{OWNER}}

---

## Phase 0 — Assessment

- [ ] Inventory row completed in workspace manifest
- [ ] Migration tier assigned (A / B / C / D)
- [ ] Linux build command recorded and succeeds
- [ ] Windows `.vcxproj` / `.sln` paths recorded (if any)
- [ ] Dependencies listed (manual / `libs/` / Conan candidate)
- [ ] Generated sources and custom commands documented
- [ ] Platform-specific sources identified

## Phase 1 — Workflow (workspace-level, once)

- [ ] `tools/ai-rules/` submodule present
- [ ] Root `AGENTS.md` references shared policy
- [ ] Local `docs/migration/` directory exists

## Phase 2 — Normalize Linux CMake

- [ ] `add_library` / `add_executable` with clear target name(s)
- [ ] Sources via `target_sources` (no new `GLOB` unless justified)
- [ ] Includes via `target_include_directories` (PUBLIC/PRIVATE correct)
- [ ] Definitions via `target_compile_definitions`
- [ ] Compile/link options via `target_compile_options` / `target_link_options`
- [ ] Link via `target_link_libraries` to CMake targets or imported targets
- [ ] Global `include_directories` / `add_definitions` removed or isolated
- [ ] Linux build passes after refactor

## Phase 3 — Visual Studio → CMake

- [ ] `.vcxproj` settings extracted to mapping worksheet
- [ ] Configuration-specific flags mapped to generator expressions
- [ ] Custom build / codegen → `add_custom_command` + `GENERATED` sources
- [ ] Post-build steps ported or replaced
- [ ] Windows CMake build via VS folder mode succeeds
- [ ] Parity validation: MSBuild log vs CMake build compared
- [ ] Parity sign-off recorded with dated notes
- [ ] Team switched daily Windows workflow to CMake (not `.vcxproj` edits)

## Phase 4 — Conan (project dependencies)

- [ ] Manual include/lib paths identified for this project
- [ ] Dependencies available in workspace `conanfile.py`
- [ ] `find_package` + imported targets used in CMake
- [ ] Linux build verified with Conan toolchain
- [ ] Windows build verified with Conan toolchain
- [ ] macOS local build verified (preset + Conan)
- [ ] macOS CI build verified

## Phase 5 — Presets

- [ ] Linux: Ninja preset builds (`{{LINUX_PRESET}}`)
- [ ] macOS: Ninja preset builds (`{{MACOS_PRESET}}`)
- [ ] Windows Ninja: preset builds (`{{WINDOWS_NINJA_PRESET}}`)
- [ ] Windows VS generator: multi-config preset builds (`{{WINDOWS_VS_PRESET}}`) — Debug and Release
- [ ] Separate `binaryDir` per preset (no generator mixing)
- [ ] CI: Linux + macOS + Windows jobs documented; VS generator Release gates installer if applicable
- [ ] Documented in consumer `AGENTS.md`

## Phase 6 — Deprecation

- [ ] Legacy Linux-only path retired
- [ ] Proven local CMake builds on Linux, Windows, and macOS
- [ ] Proven CI CMake builds on Linux, Windows, and macOS (Windows includes VS generator Release if installers use MSBuild)
- [ ] `.vcxproj` / `.sln` removed from repo (after local + CI proof — no arbitrary delay)
- [ ] Status doc marked **migration complete**
- [ ] Downstream projects confirmed not referencing removed VS projects

---

## Definition of done

Project **{{PROJECT_NAME}}** is migrated when all Phase 2–6 boxes applicable to this project are checked and parity sign-off is archived in `docs/migration/projects/{{PROJECT_SLUG}}.md`.