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

Installer Migration Module owns install-time upgrade safety

• Status: Accepted
• Date: 2026-05-11

We decided to introduce an explicit Installer Migration Module for install-time file moves, removals, config rewrites, and user-data preservation. Installer upgrade behavior must be represented as versioned migration records that produce a dry-run plan before applying changes.

Decision

• Add an Installer Migration Module as the owner for upgrade migrations.
• Keep the existing installer materialization pipeline, but move cleanup and feature-retirement behavior into migration records over time.
• Track applied migrations in an install-state file next to the existing file manifest.
• Treat the existing file manifest as the managed-file ownership baseline.
• Treat user-owned artifacts as a single shared policy consumed by preservation and manifest writing.
• 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

Every migration that rewrites runtime config, moves an invocation surface, or retires a generated runtime artifact must cite the registry row in docs/installer-migrations.md. If the migration changes where a runtime loads commands, skills, agents, hooks, or rules, the PR must update both the registry and docs/ARCHITECTURE.md.

The registry records what MSD installs, where it installs it, when migrations may touch it, who owns the surrounding config, and why the shape matches the host runtime. When upstream docs do not publish an API or docs version, the checked date is the drift sentinel. A later upstream docs or CLI release that changes command, skill, agent, hook, or rule loading requires a new registry snapshot before migration work proceeds.

Consequences

• Retiring features requires an explicit migration instead of a hidden cleanup block.
• The installer can remove stale MSD-owned artifacts without guessing about user files.
• Locally modified managed files get a consistent backup path before removal or replacement.
• Future rollback work can become runtime-neutral instead of Codex-specific.
• Migration authors must define ownership evidence, conflict behavior, runtime scope, and non-interactive behavior.
• Migration authors must also define which runtime contract they are relying on and whether the upstream documentation is versioned.
• The installer gains another state file, so tests must cover missing, legacy, and checksum-mismatch state.

Scope

The first implementation should extract manifest/user-owned helpers, add install-state persistence, add migration planning, and port one existing orphan cleanup into the migration runner. It should not rewrite every runtime installer branch in the first pass.

The detailed module contract lives in docs/installer-migrations.md.

Amendment (2026-05-11): Authoring guard enforcement

The Installer Migration Authoring Guard Module validates migration records and planned actions before planning can proceed. Records must declare title, description, introduction version, explicit install scopes, destructive status, and a plan function. Destructive or config-rewrite actions must include ownership evidence, and runtime config rewrites must cite the runtime configuration contract registry.

Amendment (2026-08-07): Non-recursive empty-directory removal primitive

Migration 003's docblock records, as an intentional consequence of this ADR, that the framework has no recursive directory-removal primitive: every action targets a single file by relPath, and an emptied directory shell is left behind for the user (or a future migration) to clean up. #3023 exposed a case where that is not enough: pi reserves the directory NAME hooks/ for its own deprecated-extension check, which warns on the path's mere existence regardless of contents. Leaving an emptied hooks/ shell behind would keep the warning firing forever, defeating the retirement.

We added remove-empty-dir, a new action type, rather than relaxing the "never remove directories" posture generally:

• It calls fs.rmdirSync only — never fs.rmSync, { recursive: true }, or { force: true }. A non-empty directory fails the underlying syscall and is treated as a successful no-op (skipped-not-empty), not swept.
• Emptiness is re-checked immediately before the call, not trusted from planning time, so a file that survived an earlier action in the same run (a failed removal, or a legitimately preserved unknown file) keeps the directory alive.
• The target must not be a symlink, and its realpath must resolve strictly inside — and never equal — the config directory's own realpath.
• Any unexpected failure degrades to left-in-place, matching every sibling action type's non-throwing posture.

Recursive directory removal remains deliberately absent. This primitive only retires a directory NODE once every file inside it has already been individually classified and actioned by other, ordinary file-level actions in the same migration — it is not a shortcut for sweeping a subtree in one step, and a migration author who wants that should still enumerate files individually per migration 003's and 009's pattern.

See docs/installer-migrations.md#action-types (remove-empty-dir) and src/installer-migrations/009-pi-retire-reserved-hooks-dir.cts.