fix(#670): self-healing recovery for installer-migration checksum drift (#675)

Editing the body of an already-released installer migration drifts its computed
checksum (it hashes plan.toString()). The integrity guard then hard-aborted
every prior install on upgrade with "applied migration checksum changed" — a
100% reproducible blocker (v1.3.0, all platforms).

Already-applied migrations are filtered out of `pending` and never re-run, so
a drifted checksum is functionally inert. ADR-0008 anticipates checksum-mismatch
state as something the install-state layer must handle gracefully (plan -> apply
-> recover/report), not abort on.

This supersedes the published-checksum allowlist merged in #674 (per-release
maintenance debt — every historical checksum hand-pinned, still throws for any
unregistered value) with a general, self-healing recovery:

- Replace the throwing guard with non-fatal `collectAppliedChecksumDrift`,
  surfaced on `plan.checksumDrift`.
- Reconcile drifted stored checksums durably on the next state write
  (`reconcileDriftedChecksums`), idempotently (no perpetual writes).
- Relocate the "shipped migration bodies are immutable" rule to a CI baseline
  test that locks every shipped migration's checksum and fails on body drift —
  where #615 should have been caught, instead of blocking users.

Removes #674's legacyChecksums field, per-migration checksum pins,
published-checksums.json fixture, and compat test.

Fixes #670

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-04 13:44:05 -04:00
committed by GitHub
parent cb09aed208
commit cdd78bd2aa
14 changed files with 279 additions and 226 deletions

View File

@@ -171,8 +171,6 @@ interface InstallerMigration {
title: string;
description: string;
introducedIn: string;
checksum: string;
legacyChecksums?: string[];
scopes: string[];
destructive: boolean;
plan: (ctx: PlanContext) => BaselineAction[];
@@ -183,10 +181,6 @@ const migration: InstallerMigration = {
title: 'Record first-time installer migration baseline',
description: 'Classify existing install surfaces before destructive installer migrations run.',
introducedIn: '1.50.0',
checksum: 'sha256:4ec58d35b30dbf39cc56e3972146086d8d31861ecd800cf0b37a7aa94fe74c2a',
legacyChecksums: [
'sha256:34608ea4e2f4e1c53b069604892860e603600d8573cc6a5584e4194044b48e67',
],
scopes: ['global', 'local'],
destructive: false,
plan: ({ configDir, runtime, baselineScan, classifyArtifact }: PlanContext): BaselineAction[] => {

View File

@@ -31,8 +31,6 @@ interface InstallerMigration {
title: string;
description: string;
introducedIn: string;
checksum: string;
legacyChecksums?: string[];
scopes: string[];
destructive: boolean;
plan: (ctx: MigrationPlanContext) => MigrationAction[];
@@ -48,10 +46,6 @@ const migration: InstallerMigration = {
title: 'Remove manifest-managed legacy orphan hook files',
description: 'Remove legacy orphan hook files that are still manifest-managed.',
introducedIn: '1.50.0',
checksum: 'sha256:e492698748a2436a12a55f0940f539b9bf651d8ffcac6f60cd856a6dabd6788c',
legacyChecksums: [
'sha256:4488e38c127a5225b31016918bcbc85ba3fd3139291ad407b94e76c03c0b89d3',
],
scopes: ['global', 'local'],
destructive: true,
// Retired generated hook files are removed only with manifest-managed

View File

@@ -48,8 +48,6 @@ interface InstallerMigration {
title: string;
description: string;
introducedIn: string;
checksum: string;
legacyChecksums?: string[];
runtimes: string[];
scopes: string[];
destructive: boolean;
@@ -112,10 +110,6 @@ const migration: InstallerMigration = {
title: 'Remove legacy Codex hooks.json GSD hook registrations',
description: 'Remove legacy Codex hooks.json GSD hook registrations after config.toml migration.',
introducedIn: '1.50.0',
checksum: 'sha256:5ce55294aa02f25758f604a569c899a6d2d060299189f5f447f68d8033157058',
legacyChecksums: [
'sha256:41f1545704dc72dfc3ab019207677a8652e389b200e8c450d52317df5bc198da',
],
runtimes: ['codex'],
scopes: ['global', 'local'],
destructive: true,

View File

@@ -48,7 +48,6 @@ interface InstallerMigration {
title: string;
description: string;
introducedIn: string;
checksum: string;
scopes: string[];
destructive: boolean;
plan(ctx: MigrationPlanContext): MigrationAction[];
@@ -81,7 +80,6 @@ const migration: InstallerMigration = {
'After the config dir rename from get-shit-done/ to gsd-core/ (#604), remove prior-manifest-managed files ' + // gsd-allow-legacy-name
'from the stale legacy directory during install (framework rollback restores them if install fails). User-added files are preserved.',
introducedIn: '1.2.0',
checksum: 'sha256:3a9f1d97f64097fb313203d19c6d93a187a38df61dd299afa5eef73e16124e95',
scopes: ['global', 'local'],
destructive: true,
plan(ctx: MigrationPlanContext): MigrationAction[] {