@opengsd/gsd-core 1.3.0-rc.1 → 1.3.0

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -0,0 +1,347 @@
+"use strict";
+/**
+ * Installer migration report utilities (ADR-457 build-at-publish: the
+ * hand-written bin/lib/installer-migration-report.cjs collapsed to a TypeScript
+ * source of truth). Behaviour is preserved byte-for-behaviour from the prior
+ * hand-written .cjs; only types are added.
+ *
+ * Resolution environment variable surface for #3541 — when the installer
+ * runs without a TTY (typical /gsd:update path via Claude Code or any
+ * scripted update), prompt-user migration actions cannot be answered
+ * interactively. Classification-based defaults apply; anything else falls
+ * through to the hard assertion with a grouped, actionable error message.
+ *
+ * docs/installer-migrations.md#prompt-user-resolution for the spec.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLED_GSD_HOOK_FILES = exports.RESOLUTION_ENV_VAR = void 0;
+exports.summarizeInstallerMigrationResult = summarizeInstallerMigrationResult;
+exports.classifyPromptUserAction = classifyPromptUserAction;
+exports.resolveInstallerMigrationPromptsForNonTty = resolveInstallerMigrationPromptsForNonTty;
+exports.assertInstallerMigrationsUnblocked = assertInstallerMigrationsUnblocked;
+exports.RESOLUTION_ENV_VAR = 'GSD_INSTALLER_MIGRATION_RESOLVE';
+const VALID_CHOICES = ['keep', 'remove'];
+// #3628: explicit whitelist of bundled hook files shipped in the npm
+// distribution under `hooks/`. The classifier-based auto-removal of these
+// files at first-time-baseline scan (added in #3610) is restricted to this
+// set — a shape regex like `^hooks/gsd-[^/]+\.(?:js|sh|cjs|mjs)$` also
+// matches user-authored custom hooks and retired bundled hooks from prior
+// versions, and auto-removing those is silent data loss.
+//
+// The bug-3628 regression guard asserts this Set stays aligned with the
+// on-disk `hooks/` directory in both directions: whitelist-but-missing
+// AND shipped-but-not-whitelisted both fail CI.
+exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
+    'hooks/gsd-check-update-worker.js',
+    'hooks/gsd-check-update.js',
+    'hooks/gsd-context-monitor.js',
+    'hooks/gsd-graphify-update.sh',
+    'hooks/gsd-phase-boundary.sh',
+    'hooks/gsd-prompt-guard.js',
+    'hooks/gsd-read-guard.js',
+    'hooks/gsd-read-injection-scanner.js',
+    'hooks/gsd-session-state.sh',
+    'hooks/gsd-statusline.js',
+    'hooks/gsd-update-banner.js',
+    'hooks/gsd-validate-commit.sh',
+    'hooks/gsd-workflow-guard.js',
+    'hooks/gsd-worktree-path-guard.js',
+]));
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function installerMigrationActionLabel(action) {
+    if (!action || !action.type)
+        return 'skipped';
+    if (action.type === 'backup-and-remove')
+        return 'backed up and removed';
+    if (action.type === 'remove-managed')
+        return 'removed';
+    if (action.type === 'rewrite-json')
+        return action.deleteIfEmpty ? 'rewrote or removed' : 'rewrote';
+    if (action.type === 'record-baseline')
+        return 'recorded';
+    if (action.type === 'baseline-preserve-user')
+        return 'preserved';
+    if (action.type === 'preserve-user')
+        return 'preserved';
+    if (action.type === 'prompt-user')
+        return 'blocked';
+    return 'skipped';
+}
+function blockedInstallerMigrationActions(result) {
+    if (result && Array.isArray(result.blocked))
+        return result.blocked;
+    const plan = result && result.plan;
+    if (plan && Array.isArray(plan.blocked))
+        return plan.blocked;
+    return [];
+}
+function baselineSummaryLabel(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function baselineSummaryRow(type, actions) {
+    const count = actions.length;
+    if (type === 'record-baseline') {
+        return {
+            label: 'recorded',
+            relPath: baselineSummaryLabel(count, 'managed baseline file'),
+            reason: 'first-time baseline scan',
+            action: { type: 'record-baseline-summary', count, actions },
+        };
+    }
+    return {
+        label: 'preserved',
+        relPath: baselineSummaryLabel(count, 'user baseline file'),
+        reason: 'first-time baseline scan',
+        action: { type: 'baseline-preserve-user-summary', count, actions },
+    };
+}
+function summarizeInstallerMigrationResult(result) {
+    const plan = result && result.plan;
+    const actions = plan && Array.isArray(plan.actions) ? plan.actions : [];
+    const blocked = blockedInstallerMigrationActions(result);
+    const blockedSet = new Set(blocked);
+    const rows = [];
+    const baselineIndexes = new Map();
+    const baselineActions = new Map();
+    for (const action of actions) {
+        const type = action && action.type;
+        if (type === 'record-baseline' || type === 'baseline-preserve-user') {
+            if (!baselineActions.has(type)) {
+                baselineActions.set(type, []);
+                baselineIndexes.set(type, rows.length);
+                rows.push(null);
+            }
+            baselineActions.get(type).push(action);
+            continue;
+        }
+        rows.push({
+            label: blockedSet.has(action) ? 'blocked' : installerMigrationActionLabel(action),
+            relPath: action.relPath ?? '',
+            reason: action.reason || '',
+            action,
+        });
+    }
+    // Phase 4 requires action reporting without flooding first-time baseline installs:
+    // docs/installer-migrations.md#phase-4-installupdate-integration.
+    for (const [type, baselineRows] of baselineActions) {
+        rows[baselineIndexes.get(type)] = baselineSummaryRow(type, baselineRows);
+    }
+    return {
+        hasReportableActions: actions.length > 0 || blocked.length > 0,
+        blocked,
+        rows,
+    };
+}
+// Classify a blocked prompt-user action into one of the safe-default
+// categories. Returns null when no safe default applies — caller must
+// fall back to the hard assertion / interactive prompt for those.
+//
+// Stale SDK build artifacts live under gsd-core/sdk/{dist,src}/
+// and are regenerated on every install, so removing them is lossless.
+// User-facing skill anchors are the .md files that surface as commands
+// to the user — these are user-owned and must be kept.
+function classifyPromptUserAction(action) {
+    const relPath = action && action.relPath;
+    if (typeof relPath !== 'string' || !relPath)
+        return null;
+    if (/^gsd-core\/sdk\/(dist|src)\//.test(relPath)) {
+        return { category: 'stale-sdk-build-artifact', choice: 'remove' };
+    }
+    if (/^skills\/gsd-[^/]+\/SKILL\.md$/.test(relPath)) {
+        return { category: 'user-facing-skill', choice: 'keep' };
+    }
+    // #3610 / #3628: bundled GSD hooks shipped under `hooks/`. The whitelist
+    // is the explicit set of filenames in the npm distribution — files that
+    // match the shape but are NOT in the whitelist (user-authored hooks,
+    // retired hooks from prior versions) fall through to the block-or-prompt
+    // flow so the user retains control. On a first-time-baseline scan the
+    // installer can safely remove whitelisted hooks because it is about to
+    // write the fresh bundled versions in their place.
+    if (exports.BUNDLED_GSD_HOOK_FILES.has(relPath)) {
+        return { category: 'bundled-gsd-hook', choice: 'remove' };
+    }
+    return null;
+}
+// Convert a blocked prompt-user action into a concrete plan action.
+// `keep` → baseline-preserve-user (idempotent — already on disk).
+// `remove` → backup-and-remove (safe: keeps a rollback copy in the
+// migration journal under gsd-migration-journal/<runId>-backups/).
+function materializeResolution(action, choice) {
+    const base = {
+        type: '', // overridden in each return branch below
+        migrationId: action.migrationId,
+        migrationChecksum: action.migrationChecksum,
+        relPath: action.relPath,
+        reason: action.reason,
+        classification: action.classification,
+        originalHash: action.originalHash || null,
+        currentHash: action.currentHash || null,
+        requestedType: 'prompt-user',
+    };
+    if (choice === 'keep') {
+        return { ...base, type: 'baseline-preserve-user' };
+    }
+    // 'remove'
+    return { ...base, type: 'backup-and-remove', backupRelPath: null };
+}
+function normalizeResolutionChoice(rawValue) {
+    if (typeof rawValue !== 'string')
+        return null;
+    const normalized = rawValue.trim().toLowerCase();
+    return VALID_CHOICES.includes(normalized) ? normalized : null;
+}
+function actionSupportsChoice(action, choice) {
+    if (!action || !choice)
+        return false;
+    if (!Array.isArray(action.choices) || action.choices.length === 0) {
+        return VALID_CHOICES.includes(choice);
+    }
+    return action.choices.includes(choice);
+}
+// Resolve prompt-user actions when stdin is not a TTY. Mutates the
+// passed result so:
+//   - resolved actions are appended to plan.actions in their concrete
+//     form (baseline-preserve-user / backup-and-remove);
+//   - result.blocked and plan.blocked are filtered to actions that
+//     could NOT be safely defaulted (caller must still handle those).
+// Returns { result, resolutions } where `resolutions` is the structured
+// log of every defaulted resolution.
+function resolveInstallerMigrationPromptsForNonTty(result, options = {}) {
+    if (!result || typeof result !== 'object') {
+        return { result, resolutions: [] };
+    }
+    const blocked = blockedInstallerMigrationActions(result);
+    if (blocked.length === 0) {
+        return { result, resolutions: [] };
+    }
+    const isTty = options.isTty === true;
+    if (isTty) {
+        // Honour interactive prompting paths (not implemented yet — the
+        // hard throw is still the right behaviour for TTY runs); resolver
+        // only fires when the installer cannot interactively ask.
+        return { result, resolutions: [] };
+    }
+    const env = options && options.env && typeof options.env === 'object'
+        ? options.env
+        : process.env;
+    const envChoice = normalizeResolutionChoice(env && env[exports.RESOLUTION_ENV_VAR]);
+    const resolutions = [];
+    const unresolved = [];
+    for (const action of blocked) {
+        if (action && action.type === 'prompt-user') {
+            let category = null;
+            let choice = null;
+            let source = null;
+            if (envChoice && actionSupportsChoice(action, envChoice)) {
+                category = 'operator-override';
+                choice = envChoice;
+                source = exports.RESOLUTION_ENV_VAR;
+            }
+            else {
+                const classification = classifyPromptUserAction(action);
+                if (classification) {
+                    category = classification.category;
+                    choice = classification.choice;
+                    source = 'non-tty-default';
+                }
+            }
+            if (choice) {
+                const resolved = materializeResolution(action, choice);
+                // Replace the original prompt-user action in-place when present so
+                // applyInstallerMigrationPlan never sees an unsupported action type.
+                // Fallback to append only when the blocked action did not originate
+                // from plan.actions (defensive).
+                if (result.plan && Array.isArray(result.plan.actions)) {
+                    const idx = result.plan.actions.indexOf(action);
+                    if (idx >= 0) {
+                        result.plan.actions[idx] = resolved;
+                    }
+                    else {
+                        result.plan.actions.push(resolved);
+                    }
+                }
+                resolutions.push({
+                    relPath: action.relPath,
+                    category: category ?? '',
+                    choice: choice ?? '',
+                    reason: action.reason,
+                    resolvedActionType: resolved.type,
+                    source: source ?? '',
+                });
+                continue;
+            }
+        }
+        unresolved.push(action);
+    }
+    // Mutate both the top-level and plan.blocked surfaces so downstream
+    // callers (assertInstallerMigrationsUnblocked, summarizers) see the
+    // post-resolution state.
+    if (Array.isArray(result.blocked)) {
+        result.blocked = unresolved;
+    }
+    if (result.plan && Array.isArray(result.plan.blocked)) {
+        result.plan.blocked = unresolved;
+    }
+    return { result, resolutions };
+}
+// Group blocked prompt-user actions by their `reason` so the operator
+// sees one summary line per cause instead of N path lines for the
+// same underlying issue.
+function groupBlockedByReason(blocked) {
+    const byReason = new Map();
+    for (const action of blocked) {
+        const reason = (action && action.reason) || 'no reason given';
+        if (!byReason.has(reason))
+            byReason.set(reason, []);
+        byReason.get(reason).push(action);
+    }
+    return byReason;
+}
+function describeChoicesForActions(blocked) {
+    const choiceSet = new Set();
+    for (const action of blocked) {
+        if (action && Array.isArray(action.choices)) {
+            for (const choice of action.choices)
+                choiceSet.add(choice);
+        }
+    }
+    if (choiceSet.size === 0) {
+        for (const fallback of VALID_CHOICES)
+            choiceSet.add(fallback);
+    }
+    return [...choiceSet];
+}
+function buildBlockedErrorMessage(blocked) {
+    const byReason = groupBlockedByReason(blocked);
+    const totalFiles = blocked.length;
+    const choices = describeChoicesForActions(blocked);
+    const lines = [
+        `installer migration blocked pending user choice: ${totalFiles} file${totalFiles === 1 ? '' : 's'} need a decision`,
+        `  choices: [${choices.join(', ')}]`,
+    ];
+    for (const [reason, actions] of byReason) {
+        lines.push(`  - ${actions.length} file${actions.length === 1 ? '' : 's'}: ${reason}`);
+        // Show up to 3 sample paths so operators can spot which files are
+        // affected without dumping a thousand-line wall when SDK build
+        // artifacts leak.
+        const sample = actions.slice(0, 3).map((a) => a.relPath);
+        if (sample.length > 0) {
+            lines.push(`      e.g. ${sample.join(', ')}${actions.length > sample.length ? `, ... (+${actions.length - sample.length} more)` : ''}`);
+        }
+    }
+    lines.push(`  resolve non-interactively by setting ${exports.RESOLUTION_ENV_VAR}=<choice> ` +
+        `(or run the installer in a TTY to be prompted per file).`);
+    return lines.join('\n');
+}
+function assertInstallerMigrationsUnblocked(result) {
+    const blocked = blockedInstallerMigrationActions(result);
+    if (blocked.length === 0)
+        return;
+    const message = buildBlockedErrorMessage(blocked);
+    const error = Object.assign(new Error(message), {
+        blocked,
+        blockedByReason: Object.fromEntries(groupBlockedByReason(blocked)),
+        resolutionEnvVar: exports.RESOLUTION_ENV_VAR,
+    });
+    throw error;
+}

package/gsd-core/bin/lib/installer-migrations/000-first-time-baseline.cjs

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Installer migration: record first-time installer migration baseline.
+ *
+ * ADR-457 build-at-publish: the hand-written
+ * bin/lib/installer-migrations/000-first-time-baseline.cjs collapsed to a
+ * TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const BASELINE_MIGRATION_ID = '2026-05-11-first-time-baseline-scan';
+// Runtime install surfaces must stay aligned with:
+// - docs/installer-migrations.md#runtime-configuration-contract-registry
+// - docs/ARCHITECTURE.md#runtime-install-contract-matrix
+const RUNTIME_SURFACES = {
+    claude: ['gsd-core', 'commands/gsd', 'skills', 'agents', 'hooks', 'settings.json'],
+    codex: ['gsd-core', 'skills', 'agents', 'hooks', 'config.toml', 'hooks.json'],
+    gemini: ['gsd-core', 'commands/gsd', 'hooks'],
+    opencode: ['gsd-core', 'command', 'skills', 'agents'],
+    kilo: ['gsd-core', 'command', 'skills', 'agents'],
+    copilot: ['gsd-core', 'skills', 'agents'],
+    antigravity: ['gsd-core', 'skills', 'agents'],
+    cursor: ['gsd-core', 'skills', 'agents'],
+    windsurf: ['gsd-core', 'skills', 'agents', 'rules'],
+    augment: ['gsd-core', 'skills', 'agents'],
+    trae: ['gsd-core', 'skills', 'agents', 'rules'],
+    qwen: ['gsd-core', 'skills', 'agents'],
+    hermes: ['gsd-core', 'skills/gsd', 'agents'],
+    cline: ['gsd-core', 'skills', 'agents'],
+    codebuddy: ['gsd-core', 'skills', 'agents'],
+};
+const COMMON_SURFACES = ['gsd-core', 'skills', 'agents', 'hooks'];
+const INTERNAL_TOP_LEVEL_NAMES = new Set([
+    'gsd-file-manifest.json',
+    'gsd-install-state.json',
+    'gsd-migration-backups',
+    'gsd-migration-journal',
+]);
+const USER_OWNED_PATHS = new Set([
+    'gsd-core/USER-PROFILE.md',
+    'commands/gsd/dev-preferences.md',
+    'skills/gsd-dev-preferences/SKILL.md',
+]);
+let knownGeneratedAgentNames = null;
+function normalizeRelPath(relPath) {
+    return relPath.replace(/\\/g, '/').replace(/^\/+/, '');
+}
+function baselineInstallSurfaces(runtime) {
+    if (runtime && RUNTIME_SURFACES[runtime])
+        return RUNTIME_SURFACES[runtime];
+    return COMMON_SURFACES;
+}
+function walkFiles(root, relDir, files) {
+    const dir = node_path_1.default.join(root, relDir);
+    if (!node_fs_1.default.existsSync(dir))
+        return;
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        if (relDir === '' && INTERNAL_TOP_LEVEL_NAMES.has(entry.name))
+            continue;
+        if (entry.isDirectory()) {
+            walkFiles(root, relPath, files);
+        }
+        else if (entry.isFile()) {
+            files.add(normalizeRelPath(relPath));
+        }
+    }
+}
+function scanBaselineFiles(configDir, runtime) {
+    const relPaths = new Set();
+    for (const surface of baselineInstallSurfaces(runtime)) {
+        const normalized = normalizeRelPath(surface);
+        const fullPath = node_path_1.default.join(configDir, normalized);
+        if (!node_fs_1.default.existsSync(fullPath))
+            continue;
+        const stat = node_fs_1.default.statSync(fullPath);
+        if (stat.isDirectory()) {
+            walkFiles(configDir, normalized, relPaths);
+        }
+        else if (stat.isFile() && !INTERNAL_TOP_LEVEL_NAMES.has(normalized)) {
+            relPaths.add(normalized);
+        }
+    }
+    return [...relPaths];
+}
+function isUserOwnedBaselinePath(relPath) {
+    if (USER_OWNED_PATHS.has(relPath))
+        return true;
+    const parts = relPath.split('/');
+    if (parts[0] === 'skills' && parts[1] && !parts[1].startsWith('gsd-'))
+        return true;
+    if (parts[0] === 'agents' && parts[1] && !parts[1].startsWith('gsd-'))
+        return true;
+    return false;
+}
+function listKnownGeneratedAgentNames() {
+    if (knownGeneratedAgentNames)
+        return knownGeneratedAgentNames;
+    knownGeneratedAgentNames = new Set();
+    const agentsDir = node_path_1.default.resolve(__dirname, '..', '..', '..', '..', 'agents');
+    try {
+        for (const entry of node_fs_1.default.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.startsWith('gsd-') && entry.name.endsWith('.md')) {
+                knownGeneratedAgentNames.add(entry.name.replace(/\.md$/, ''));
+            }
+        }
+    }
+    catch {
+        // If the source agent directory is unavailable, fail closed and treat
+        // GSD-looking agent files as user-choice artifacts.
+    }
+    return knownGeneratedAgentNames;
+}
+function isKnownGeneratedAgentPath(relPath, runtime) {
+    const parts = relPath.split('/');
+    if (parts.length !== 2 || parts[0] !== 'agents')
+        return false;
+    const fileName = parts[1];
+    const extension = node_path_1.default.posix.extname(fileName);
+    if (extension !== '.md' && !(runtime === 'codex' && extension === '.toml'))
+        return false;
+    const agentName = fileName.slice(0, -extension.length);
+    return listKnownGeneratedAgentNames().has(agentName);
+}
+function isStaleGsdLookingPath(relPath) {
+    const baseName = node_path_1.default.posix.basename(relPath);
+    if (/^gsd[-_]/.test(baseName))
+        return true;
+    const parts = relPath.split('/');
+    if ((parts[0] === 'skills' || parts[0] === 'agents') && parts[1] && parts[1].startsWith('gsd-')) {
+        return true;
+    }
+    return false;
+}
+function baselineActionRank(action) {
+    if (action.type === 'record-baseline')
+        return 0;
+    if (action.type === 'baseline-preserve-user')
+        return 1;
+    return 2;
+}
+const migration = {
+    id: BASELINE_MIGRATION_ID,
+    title: 'Record first-time installer migration baseline',
+    description: 'Classify existing install surfaces before destructive installer migrations run.',
+    introducedIn: '1.50.0',
+    scopes: ['global', 'local'],
+    destructive: false,
+    plan: ({ configDir, runtime, baselineScan, classifyArtifact }) => {
+        if (!baselineScan)
+            return [];
+        const actions = [];
+        for (const relPath of scanBaselineFiles(configDir, runtime)) {
+            // docs/installer-migrations.md#baseline-preserve-user keeps user-owned
+            // artifacts out of destructive migration flow.
+            if (isUserOwnedBaselinePath(relPath)) {
+                actions.push({
+                    type: 'baseline-preserve-user',
+                    relPath,
+                    reason: 'known user-owned artifact preserved by first-time migration baseline',
+                    classification: 'user-owned',
+                    originalHash: null,
+                    currentHash: null,
+                });
+                continue;
+            }
+            const artifact = classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine' || artifact.classification === 'managed-modified') {
+                actions.push({
+                    type: 'record-baseline',
+                    relPath,
+                    reason: 'existing manifest-managed file included in first-time migration baseline',
+                });
+                continue;
+            }
+            const currentHash = artifact.currentHash ?? null;
+            if (isKnownGeneratedAgentPath(relPath, runtime)) {
+                actions.push({
+                    type: 'record-baseline',
+                    relPath,
+                    reason: 'known installer-generated agent included in first-time migration baseline',
+                    classification: artifact.classification,
+                    originalHash: artifact.originalHash ?? null,
+                    currentHash,
+                });
+                continue;
+            }
+            if (isStaleGsdLookingPath(relPath)) {
+                actions.push({
+                    type: 'prompt-user',
+                    relPath,
+                    reason: 'GSD-looking file is not proven manifest-managed and needs explicit user choice',
+                    classification: 'stale-gsd-looking',
+                    originalHash: artifact.originalHash ?? null,
+                    currentHash,
+                    prompt: 'Choose whether to remove this stale-looking GSD artifact or keep it as user-owned.',
+                    choices: ['keep', 'remove'],
+                });
+                continue;
+            }
+            actions.push({
+                type: 'baseline-preserve-user',
+                relPath,
+                reason: 'unknown install-surface file preserved by first-time migration baseline',
+                classification: artifact.classification,
+                originalHash: artifact.originalHash ?? null,
+                currentHash,
+            });
+        }
+        return actions.sort((left, right) => baselineActionRank(left) - baselineActionRank(right) || left.relPath.localeCompare(right.relPath));
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/001-legacy-orphan-files.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Installer migration: remove manifest-managed legacy orphan hook files
+ * (ADR-457 build-at-publish: the hand-written
+ * bin/lib/installer-migrations/001-legacy-orphan-files.cjs collapsed to a
+ * TypeScript source of truth). Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+const LEGACY_ORPHAN_FILES = [
+    'hooks/gsd-notify.sh',
+    'hooks/statusline.js',
+];
+const migration = {
+    id: '2026-05-11-legacy-orphan-files',
+    title: 'Remove manifest-managed legacy orphan hook files',
+    description: 'Remove legacy orphan hook files that are still manifest-managed.',
+    introducedIn: '1.50.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    // Retired generated hook files are removed only with manifest-managed
+    // evidence. This follows docs/installer-migrations.md#ownership and avoids
+    // relying on whether a runtime currently registers host hook config in the
+    // runtime contract registry.
+    plan: (ctx) => {
+        const actions = [];
+        for (const relPath of LEGACY_ORPHAN_FILES) {
+            const artifact = ctx.classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine') {
+                actions.push({
+                    type: 'remove-managed',
+                    relPath,
+                    reason: 'legacy orphan hook file retired by installer migration',
+                    ownershipEvidence: 'legacy hook path is manifest-managed in gsd-file-manifest.json',
+                });
+            }
+            else if (artifact.classification === 'managed-modified') {
+                actions.push({
+                    type: 'backup-and-remove',
+                    relPath,
+                    reason: 'legacy orphan hook file retired by installer migration',
+                    ownershipEvidence: 'legacy hook path is manifest-managed in gsd-file-manifest.json',
+                });
+            }
+        }
+        return actions;
+    },
+};
+module.exports = migration;