@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/bin/lib/installer-migration-authoring.cjs

@@ -0,0 +1,117 @@
+'use strict';
+
+const path = require('path');
+
+function requireNonEmptyString(record, field, source) {
+  if (typeof record[field] !== 'string' || record[field].trim() === '') {
+    throw new Error(`migration record must include a non-empty ${field}: ${source}`);
+  }
+}
+
+function validateStringArray(record, field, source) {
+  if (record[field] === undefined) return;
+  if (
+    !Array.isArray(record[field]) ||
+    record[field].length === 0 ||
+    record[field].some((value) => typeof value !== 'string' || value.trim() === '')
+  ) {
+    throw new Error(`migration record ${field} must be a non-empty string array when provided: ${source}`);
+  }
+}
+
+function requireStringArray(record, field, source) {
+  if (
+    !Array.isArray(record[field]) ||
+    record[field].length === 0 ||
+    record[field].some((value) => typeof value !== 'string' || value.trim() === '')
+  ) {
+    throw new Error(`migration record ${field} must be a non-empty string array: ${source}`);
+  }
+}
+
+function recordSource(record, fallback) {
+  return fallback || (record && typeof record.id === 'string' && record.id.trim() ? record.id : '<unknown>');
+}
+
+function validateInstallerMigrationRecord(record, source) {
+  const displaySource = recordSource(record, source);
+  if (!record || typeof record !== 'object') {
+    throw new Error(`migration record must export an object: ${displaySource}`);
+  }
+
+  // Authoring contract follows docs/installer-migrations.md#authoring-workflow
+  // and docs/adr/0008-installer-migration-module.md#decision.
+  requireNonEmptyString(record, 'id', displaySource);
+  requireNonEmptyString(record, 'title', displaySource);
+  requireNonEmptyString(record, 'description', displaySource);
+  requireNonEmptyString(record, 'introducedIn', displaySource);
+  if (typeof record.destructive !== 'boolean') {
+    throw new Error(`migration record must declare destructive as a boolean: ${displaySource}`);
+  }
+  validateStringArray(record, 'runtimes', displaySource);
+  requireStringArray(record, 'scopes', displaySource);
+  if (typeof record.plan !== 'function') {
+    throw new Error(`migration record must include a plan function: ${displaySource}`);
+  }
+
+  return record;
+}
+
+function actionSource(migration, action) {
+  const migrationId = migration && typeof migration.id === 'string' ? migration.id : '<unknown>';
+  const relPath = action && typeof action.relPath === 'string' ? action.relPath : '<unknown>';
+  return `${migrationId} ${relPath}`;
+}
+
+function requireActionEvidence(action, field, migration) {
+  if (typeof action[field] !== 'string' || action[field].trim() === '') {
+    throw new Error(`migration action ${action.type} must include ${field}: ${actionSource(migration, action)}`);
+  }
+}
+
+function validateSafeRelPath(relPath, migration, actionType) {
+  const source = actionSource(migration, { relPath });
+  const normalized = relPath.replace(/\\/g, '/');
+  if (path.isAbsolute(normalized) || path.win32.isAbsolute(normalized)) {
+    throw new Error(`migration action ${actionType} relPath must stay inside configDir: ${source}`);
+  }
+  const segments = normalized.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new Error(`migration action ${actionType} relPath must stay inside configDir: ${source}`);
+  }
+}
+
+function validateInstallerMigrationActions(actions, migration) {
+  if (!Array.isArray(actions)) {
+    throw new Error(`migration ${migration.id} plan must return an array`);
+  }
+
+  for (const action of actions) {
+    if (!action || typeof action !== 'object') {
+      throw new Error(`migration action must be an object: ${migration.id}`);
+    }
+    if (typeof action.type !== 'string' || action.type.trim() === '') {
+      throw new Error(`migration action must include a non-empty type: ${migration.id}`);
+    }
+    if (typeof action.relPath !== 'string' || action.relPath.trim() === '') {
+      throw new Error(`migration action ${action.type} must include a non-empty relPath: ${migration.id}`);
+    }
+    validateSafeRelPath(action.relPath, migration, action.type);
+    // Ownership and runtime-contract evidence are required by
+    // docs/installer-migrations.md#action-types and
+    // docs/adr/0008-installer-migration-module.md#runtime-contract-decision.
+    if (action.type === 'remove-managed' || action.type === 'rewrite-json') {
+      requireActionEvidence(action, 'ownershipEvidence', migration);
+    }
+    if (action.type === 'rewrite-json' && (typeof migration.runtimeContract !== 'string' || migration.runtimeContract.trim() === '')) {
+      throw new Error(`migration action rewrite-json requires migration runtimeContract: ${actionSource(migration, action)}`);
+    }
+  }
+
+  return actions;
+}
+
+module.exports = {
+  validateInstallerMigrationActions,
+  validateInstallerMigrationRecord,
+};

package/get-shit-done/bin/lib/installer-migration-report.cjs

@@ -0,0 +1,354 @@
+'use strict';
+
+// 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. We resolve them by classification:
+//   - Stale SDK build artifacts (get-shit-done/sdk/{dist,src}/gsd-*):
+//     default `remove`. Fresh install supplies replacements.
+//   - User-facing skill anchors (skills/gsd-*/SKILL.md): default `keep`.
+//     User-owned content is preserved.
+// Anything else: fall through to the hard assertion with an improved,
+// grouped, actionable error message.
+//
+// docs/installer-migrations.md#prompt-user-resolution for the spec.
+const RESOLUTION_ENV_VAR = 'GSD_INSTALLER_MIGRATION_RESOLVE';
+const VALID_CHOICES = ['keep', 'remove'];
+
+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,
+  };
+}
+
+// #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.
+const 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',
+]));
+
+// 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 get-shit-done/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 (/^get-shit-done\/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 (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 = {
+    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[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 = 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,
+          choice,
+          reason: action.reason,
+          resolvedActionType: resolved.type,
+          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 ${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 = new Error(message);
+  error.blocked = blocked;
+  error.blockedByReason = Object.fromEntries(groupBlockedByReason(blocked));
+  error.resolutionEnvVar = RESOLUTION_ENV_VAR;
+  throw error;
+}
+
+module.exports = {
+  RESOLUTION_ENV_VAR,
+  BUNDLED_GSD_HOOK_FILES,
+  assertInstallerMigrationsUnblocked,
+  classifyPromptUserAction,
+  resolveInstallerMigrationPromptsForNonTty,
+  summarizeInstallerMigrationResult,
+};

package/get-shit-done/bin/lib/installer-migrations/000-first-time-baseline.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('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
+//
+// The registry rows are based on each runtime's upstream loader docs where
+// available. Source-limited rows are intentionally conservative: scan generated
+// files GSD materializes, but do not infer ownership of undocumented host config.
+const RUNTIME_SURFACES = {
+  claude: ['get-shit-done', 'commands/gsd', 'skills', 'agents', 'hooks', 'settings.json'],
+  codex: ['get-shit-done', 'skills', 'agents', 'hooks', 'config.toml', 'hooks.json'],
+  gemini: ['get-shit-done', 'commands/gsd', 'hooks'],
+  opencode: ['get-shit-done', 'command', 'skills', 'agents'],
+  kilo: ['get-shit-done', 'command', 'skills', 'agents'],
+  copilot: ['get-shit-done', 'skills', 'agents'],
+  antigravity: ['get-shit-done', 'skills', 'agents'],
+  cursor: ['get-shit-done', 'skills', 'agents'],
+  windsurf: ['get-shit-done', 'skills', 'agents', 'rules'],
+  augment: ['get-shit-done', 'skills', 'agents'],
+  trae: ['get-shit-done', 'skills', 'agents', 'rules'],
+  qwen: ['get-shit-done', 'skills', 'agents'],
+  hermes: ['get-shit-done', 'skills/gsd', 'agents'],
+  cline: ['get-shit-done', 'skills', 'agents'],
+  codebuddy: ['get-shit-done', 'skills', 'agents'],
+};
+
+const COMMON_SURFACES = ['get-shit-done', '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([
+  'get-shit-done/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 = path.join(root, relDir);
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const relPath = path.posix.join(relDir, entry.name);
+    if (relDir === '' && INTERNAL_TOP_LEVEL_NAMES.has(entry.name)) continue;
+    const fullPath = path.join(root, relPath);
+    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 = path.join(configDir, normalized);
+    if (!fs.existsSync(fullPath)) continue;
+    const stat = fs.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 = path.resolve(__dirname, '..', '..', '..', '..', 'agents');
+  try {
+    for (const entry of fs.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 = path.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 = path.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;
+}
+
+module.exports = {
+  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; classify later only when
+      // ownership is not already known.
+      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;
+      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,
+          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,
+          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,
+        currentHash,
+      });
+    }
+
+    return actions.sort((left, right) =>
+      baselineActionRank(left) - baselineActionRank(right) || left.relPath.localeCompare(right.relPath)
+    );
+  },
+};