Feature: first-class installer migration tool for safe upgrades

[trek-e]

What to build

Build a first-class Installer Migration Module that replaces ad hoc install cleanup with a planned, journaled, reviewable migration system.

This should future-proof GSD updates when features move, rename, replace, or retire installed files. The migration tool must clean up stale GSD-owned artifacts, preserve user-owned data, back up locally modified managed files, support dry-run planning, and avoid leaving hybrid installs after failures.

Design references:

• docs/installer-migrations.md
• docs/adr/0008-installer-migration-module.md

Phases

Phase 1: Foundational migration runner

Create the core migration infrastructure in one coherent pass:

• install-state read/write next to gsd-file-manifest.json
• migration record discovery
• checksum tracking
• pending/applied migration detection
• dry-run planning
• shared action model
• managed/user-owned/unknown artifact classification
• journaled apply and rollback helpers

Phase 2: Port existing cleanup behavior

Move one or more existing installer cleanup paths into the migration runner:

• orphaned hook/file cleanup
• stale runtime-generated artifacts
• config marker/section cleanup where ownership is provable

Phase 3: First-time baseline scanner

Add a baseline migration for existing installs that predate migration tracking:

• scan known install surfaces
• classify files
• preserve unknowns by default
• report ambiguous artifacts
• offer user choices in interactive mode
• block or dry-run in non-interactive mode when destructive action is ambiguous

Phase 4: Install/update integration

Wire the migration runner into normal install/update flow:

• run plan before package materialization
• apply safe migrations
• write install state after success
• report removed, backed up, preserved, skipped, and blocked actions
• keep existing install transforms working during migration adoption

Phase 5: Authoring guardrails

Add contributor-facing guardrails:

• tests for migration records
• dry-run/apply regression tests
• user-owned preservation tests
• locally modified managed-file tests
• docs for when a feature retirement requires a migration

Acceptance criteria

• Installer migrations are versioned and tracked in install state.
• The same planner powers dry-run and apply behavior.
• Managed, user-owned, and unknown artifacts are classified consistently.
• Unknown files are preserved by default.
• Locally modified managed files are backed up before removal or replacement.
• Migration apply writes a rollback journal and restores touched paths on failure where possible.
• At least one existing ad hoc cleanup path is ported into the migration runner.
• Existing installs can run a baseline scan without losing user data.
• Install/update output clearly reports what changed and what was preserved.
• Tests cover fresh install, reinstall, upgrade, modified managed files, user-owned files, unknown files, and failed apply rollback.

Blocked by

None - can start immediately