GW-037: Prove migrations, package upgrade, RC install, and rollback

[trippyogi]

Outcome

Prove the complete release-candidate lifecycle: clean install, upgrade from supported older versions, local-data migrations, packed-package behavior, MCP/CLI operation, rollback, and recovery from interrupted or failed upgrades.

The RC should be installable and reversible on a real user's machine without losing decisions, outcomes, captures, config, or the ability to return to the previous version.

Why this matters

A correct build is not enough if users cannot upgrade safely or recover from a bad release. Gitworthy stores durable local evidence that may be valuable for calibration and active work; migrations and packaging must preserve it under realistic conditions.

Scope

• Define supported upgrade sources and the expected migration path to the 0.9 RC/1.0 layout.
• Build packed tarballs and install them in clean temporary projects and representative global/npx-style environments.
• Test CLI, MCP, schemas, docs/assets, help/version, doctor, check, hunt, store, recheck, capture, brief, and eval commands from the packed artifact.
• Exercise config, ledger/store, capture, fixture, and index migrations with backups, dry-run, interruption, retry, and idempotency.
• Prove unsupported/future/corrupt data fails safely with remediation and quarantine where appropriate.
• Document rollback steps for package version and local data, including when reverse migration is required versus backup restore.
• Verify npm metadata, package contents, version sync, provenance, and release notes.
• Produce an RC install/upgrade/rollback report and sign-off checklist.

Non-goals

• No automatic mutation of user data without backup and validation.
• No support for every unpublished development snapshot.
• No rollback claim that cannot be demonstrated from real artifacts.
• No production publish in this issue; GW-038 owns final release.

Dependencies and readiness

• Depends on GW-036 / issue GW-036: Add cross-platform, cancellation, soak, fuzz, and mutation tests #45.
• Contributor readiness: BLOCKED until the reliability suite passes. Packaging and migration fixtures can be prepared earlier.

Acceptance criteria

• Clean install from the exact packed RC artifact works on supported platforms.
• Upgrade succeeds from every documented supported prior version/data layout.
• Migrations are dry-runnable, backed up, atomic or recoverable, idempotent, and schema-validated.
• Interrupted migration/install tests preserve the original usable data or a clear recovery path.
• Unsupported/future/corrupt records are never silently dropped or treated as empty.
• CLI and MCP smoke tests pass from the packed artifact, not the source tree.
• Package contains all required schemas, docs, skill, license, and runtime files and excludes secrets/dev artifacts/binaries.
• Version metadata matches across package, server/registry metadata, schemas, CLI, MCP, and changelog.
• Rollback to the previous release is documented and successfully exercised.
• RC report lists exact commands, platforms, versions, fixtures, outcomes, and unresolved risks.

Tests and validation

• Clean temp HOME and project install tests.
• Global/npx-style invocation tests.
• Supported-version migration matrix.
• Dry-run, retry, duplicate-run, stale-lock, disk-full/error-injection, and interrupted-migration scenarios.
• Backup restoration and rollback verification.
• Packed-package CLI/MCP/schema/doc asset inspection.
• npm publish dry run and provenance/metadata checks.
• Cross-platform RC smoke using the same artifact digest.

Likely implementation areas

• Release verification and package-smoke scripts.
• Migration fixtures and data doctor integration.
• CI artifact build/test jobs.
• Upgrade/rollback documentation and release checklist.
• Changelog and package metadata validation.

Compatibility and safety

Migration code is decision-critical and data-sensitive. Never delete original data until the migrated store has been fully validated; keep dated backups and explicit recovery instructions.

[trippyogi]

Upgrade smoke slice (\pnpm test:upgrade) landed in #77. Full migration matrix / interrupted migration still open.