Merge pull request #3400 from gsd-build/codex/installer-migrations-phase-three

Feat(installer): Phase 3 first-time baseline scanner

docs/ARCHITECTURE.md

@@ -627,6 +627,9 @@ Install-time file moves, stale-artifact cleanup, config rewrites, and user-data
 preservation are governed by the Installer Migration Module. See
 [Installer Migrations](installer-migrations.md) and
 [ADR 0008](adr/0008-installer-migration-module.md).
+The migration module also owns the gated first-time baseline scan for legacy
+installs, classifying known runtime install surfaces before later migrations
+remove or rewrite anything.
 
 ### Platform Handling
 

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

@@ -15,6 +15,7 @@ We decided to introduce an explicit Installer Migration Module for install-time
 - Require migrations to plan first, then apply through a shared executor that owns backup, rollback, and reporting.
 - Default ambiguous or unknown files to preserve; destructive changes need managed-file evidence or explicit user choice.
 - Support dry-run output using the same planner used by apply mode.
+- Include a first-time baseline scanner for legacy installs that need classification before destructive migrations can be trusted.
 - Treat the runtime configuration contract registry in `docs/installer-migrations.md` as the source of truth for migrations that touch host runtime config.
 
 ## Runtime Contract Decision

docs/installer-migrations.md

@@ -213,6 +213,22 @@ an explicit user choice.
 Use for profile, preferences, hand-authored instructions, and future workflow
 outputs.
 
+### record-baseline
+
+Record a manifest-managed file in the first-time baseline without mutating it.
+The executor writes a journal entry and install-state entry so later upgrades
+know the baseline scan completed.
+
+Use only from the first-time baseline scanner.
+
+### baseline-preserve-user
+
+Record a user-owned or unknown file discovered under a known install surface
+without mutating it. Unknown files default to this action unless they look like
+retired GSD-generated artifacts that need an explicit user choice.
+
+Use only from the first-time baseline scanner.
+
 ### prompt-user
 
 Stop non-interactive destructive migration and ask in interactive mode. The
@@ -365,6 +381,18 @@ It should:
 5. offer actions for ambiguous files instead of deleting them
 6. write install state after successful classification
 
+The Phase 3 implementation adds a gated baseline migration record,
+`2026-05-11-first-time-baseline-scan`. The runner passes `baselineScan: true`
+when the installer wants this first-time scan. Without that flag, discovery is
+safe for normal migration runs and the baseline record plans no actions.
+
+The baseline action contract is:
+
+- `record-baseline` for manifest-managed files
+- `baseline-preserve-user` for known user-owned files and unknown files that do
+  not look like stale GSD-generated artifacts
+- `prompt-user` for stale GSD-looking artifacts that are not manifest-proven
+
 This baseline is the escape hatch for old installs that predate full migration
 tracking. It gives the user a reviewable redistribution/removal plan without
 requiring the installer to infer every past release transition perfectly.