@fission-ai/openspec 1.14.2 → 1.15.0

package/dist/core/github-copilot/cloud-agent.js

@@ -242,10 +242,14 @@ function isLegacyCopilotCloudFile(relPath, content) {
 function isManagedCopilotCloudFile(relPath, content) {
     return isCurrentCopilotCloudFile(relPath, content) || isLegacyCopilotCloudFile(relPath, content);
 }
-async function reconcileCopilotCloudFile(fullPath, relPath) {
+const DIRECT_CLOUD_FILE_OPS = {
+    writeFile: (filePath, content) => FileSystemUtils.writeFile(filePath, content),
+    removeFile: (filePath) => fs.unlink(filePath),
+};
+async function reconcileCopilotCloudFile(fullPath, relPath, ops) {
     const currentContent = COPILOT_CLOUD_FILE_CONTENTS[relPath];
     if (!(await FileSystemUtils.fileExists(fullPath))) {
-        await FileSystemUtils.writeFile(fullPath, currentContent);
+        await ops.writeFile(fullPath, currentContent);
         return true;
     }
     const existingContent = await FileSystemUtils.readFile(fullPath);
@@ -255,7 +259,7 @@ async function reconcileCopilotCloudFile(fullPath, relPath) {
     if (!isLegacyCopilotCloudFile(relPath, existingContent)) {
         return false;
     }
-    await FileSystemUtils.writeFile(fullPath, currentContent);
+    await ops.writeFile(fullPath, currentContent);
     return true;
 }
 async function assertCreatableFilePath(filePath) {
@@ -313,7 +317,7 @@ async function classifyCopilotAgentReconciliation(agentPath, alternateAgentPath)
  *
  * @returns Object indicating which files were written.
  */
-export async function writeCopilotCloudFiles(projectPath) {
+export async function writeCopilotCloudFiles(projectPath, ops = DIRECT_CLOUD_FILE_OPS) {
     const setupStepsPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, COPILOT_CLOUD_FILES.setupSteps);
     const agentPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, COPILOT_CLOUD_FILES.agent);
     const alternateAgentPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, COPILOT_AGENT_ALTERNATE_FILE);
@@ -323,13 +327,13 @@ export async function writeCopilotCloudFiles(projectPath) {
     await assertMissingOrRegularFile(agentPath);
     await assertMissingOrRegularFile(alternateAgentPath);
     const agentReconciliation = await classifyCopilotAgentReconciliation(agentPath, alternateAgentPath);
-    const setupStepsWritten = await reconcileCopilotCloudFile(setupStepsPath, COPILOT_CLOUD_FILES.setupSteps);
+    const setupStepsWritten = await reconcileCopilotCloudFile(setupStepsPath, COPILOT_CLOUD_FILES.setupSteps, ops);
     let agentWritten = false;
     if (agentReconciliation === 'reconcile') {
-        agentWritten = await reconcileCopilotCloudFile(agentPath, COPILOT_CLOUD_FILES.agent);
+        agentWritten = await reconcileCopilotCloudFile(agentPath, COPILOT_CLOUD_FILES.agent, ops);
     }
     else if (agentReconciliation === 'remove-managed') {
-        await fs.unlink(agentPath);
+        await ops.removeFile(agentPath);
     }
     return { setupStepsWritten, agentWritten };
 }
@@ -339,7 +343,7 @@ export async function writeCopilotCloudFiles(projectPath) {
  *
  * @returns Number of files removed.
  */
-export async function removeCopilotCloudFiles(projectPath) {
+export async function removeCopilotCloudFiles(projectPath, ops = DIRECT_CLOUD_FILE_OPS) {
     let removed = 0;
     const managedPaths = Object.values(COPILOT_CLOUD_FILES).map((relPath) => ({
         relPath,
@@ -354,7 +358,7 @@ export async function removeCopilotCloudFiles(projectPath) {
             if (!isManagedCopilotCloudFile(relPath, content)) {
                 continue;
             }
-            await fs.unlink(fullPath);
+            await ops.removeFile(fullPath);
             removed++;
         }
     }

package/dist/core/global-config.d.ts

@@ -28,6 +28,8 @@ export interface GlobalConfig {
     telemetry?: TelemetryConfig;
     /** Whether the first-run shell-completions tip has been shown. */
     completionTipSeen?: boolean;
+    /** Whether the one-time note about the standalone install has been shown. */
+    standaloneTipSeen?: boolean;
 }
 /**
  * Gets the global configuration directory path following XDG Base Directory Specification.
@@ -94,4 +96,6 @@ export interface SaveGlobalConfigOptions {
  * existing file it cannot parse unless `replaceUnreadable` is set.
  */
 export declare function saveGlobalConfig(config: GlobalConfig, options?: SaveGlobalConfigOptions): void;
+/** The bytes `saveGlobalConfig` writes, for a caller that only plans the write. */
+export declare function serializeGlobalConfig(config: GlobalConfig): string;
 //# sourceMappingURL=global-config.d.ts.map

package/dist/core/global-config.js

@@ -173,6 +173,10 @@ export function saveGlobalConfig(config, options = {}) {
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
     }
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    fs.writeFileSync(configPath, serializeGlobalConfig(config), 'utf-8');
+}
+/** The bytes `saveGlobalConfig` writes, for a caller that only plans the write. */
+export function serializeGlobalConfig(config) {
+    return JSON.stringify(config, null, 2) + '\n';
 }
 //# sourceMappingURL=global-config.js.map

package/dist/core/legacy-cleanup.d.ts

@@ -166,7 +166,17 @@ export interface CleanupResult {
  * @param detection - Detection result from detectLegacyArtifacts
  * @returns Cleanup result with summary of actions taken
  */
-export declare function cleanupLegacyArtifacts(projectPath: string, detection: LegacyDetectionResult): Promise<CleanupResult>;
+/**
+ * Every change cleanup makes on disk. `update --dry-run` passes a recorder, so
+ * the plan comes from this same code rather than a description of it.
+ */
+export interface LegacyCleanupOps {
+    writeFile(filePath: string, content: string): Promise<void>;
+    removeFile(filePath: string): Promise<void>;
+    /** Removes a directory already known to be empty. */
+    removeEmptyDirectory(dirPath: string): Promise<void>;
+}
+export declare function cleanupLegacyArtifacts(projectPath: string, detection: LegacyDetectionResult, ops?: LegacyCleanupOps): Promise<CleanupResult>;
 /**
  * Generates a cleanup summary message for display.
  *

package/dist/core/legacy-cleanup.js

@@ -323,14 +323,14 @@ function legacyCommandDirForFile(file) {
  * or records what is left in it as kept. Never recursive: whatever remains was
  * not written by OpenSpec. Returns true when the directory was removed.
  */
-async function settleLegacyCommandDir(projectPath, dirPath, result) {
+async function settleLegacyCommandDir(projectPath, dirPath, result, ops = DIRECT_CLEANUP_OPS) {
     const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
     const remaining = await readLegacyCommandDir(fullPath, []);
     if (!remaining) {
         return false;
     }
     if (remaining.others.length === 0) {
-        await fs.rmdir(fullPath);
+        await ops.removeEmptyDirectory(fullPath);
         result.deletedDirs.push(dirPath);
         return true;
     }
@@ -493,15 +493,12 @@ export function isOnlyOpenSpecContent(content) {
 export function removeMarkerBlock(content) {
     return removeMarkerBlockUtil(content, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
 }
-/**
- * Cleans up legacy OpenSpec artifacts from a project.
- * Preserves openspec/project.md (shows migration hint instead of deleting).
- *
- * @param projectPath - The root path of the project
- * @param detection - Detection result from detectLegacyArtifacts
- * @returns Cleanup result with summary of actions taken
- */
-export async function cleanupLegacyArtifacts(projectPath, detection) {
+const DIRECT_CLEANUP_OPS = {
+    writeFile: (filePath, content) => FileSystemUtils.writeFile(filePath, content),
+    removeFile: (filePath) => fs.unlink(filePath),
+    removeEmptyDirectory: (dirPath) => fs.rmdir(dirPath),
+};
+export async function cleanupLegacyArtifacts(projectPath, detection, ops = DIRECT_CLEANUP_OPS) {
     const result = {
         deletedFiles: [],
         deletedFileReplacementLabels: {},
@@ -519,7 +516,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             const content = await FileSystemUtils.readFile(filePath);
             const newContent = removeMarkerBlock(content);
             // Always write the file, even if empty - never delete user config files
-            await FileSystemUtils.writeFile(filePath, newContent);
+            await ops.writeFile(filePath, newContent);
             result.modifiedFiles.push(fileName);
         }
         catch (error) {
@@ -545,10 +542,10 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
                 if (!(await isGeneratedLegacyCommand(filePath))) {
                     continue;
                 }
-                await fs.unlink(filePath);
+                await ops.removeFile(filePath);
                 deleted.push(name);
             }
-            if (!(await settleLegacyCommandDir(projectPath, dirPath, result))) {
+            if (!(await settleLegacyCommandDir(projectPath, dirPath, result, ops))) {
                 result.deletedFiles.push(...deleted.map((name) => `${dirPath}/${name}`));
             }
         }
@@ -570,7 +567,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
                     continue;
                 }
             }
-            await fs.unlink(fullPath);
+            await ops.removeFile(fullPath);
             result.deletedFiles.push(filePath);
         }
         catch (error) {
@@ -581,7 +578,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
     // file by file above; record what was left in it.
     for (const dirPath of partlyCleanedDirs) {
         try {
-            await settleLegacyCommandDir(projectPath, dirPath, result);
+            await settleLegacyCommandDir(projectPath, dirPath, result, ops);
         }
         catch (error) {
             result.errors.push(`Failed to delete directory ${dirPath}: ${error.message}`);
@@ -595,7 +592,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             continue;
         }
         try {
-            await fs.unlink(filePath);
+            await ops.removeFile(filePath);
             result.deletedFiles.push(filePath);
             const promptMatch = globalPromptMatchesByPath.get(filePath);
             if (promptMatch?.replacementLabel) {
@@ -611,7 +608,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
         const agentsPath = FileSystemUtils.joinPath(projectPath, 'openspec', 'AGENTS.md');
         if (await FileSystemUtils.fileExists(agentsPath)) {
             try {
-                await fs.unlink(agentsPath);
+                await ops.removeFile(agentsPath);
                 result.deletedFiles.push('openspec/AGENTS.md');
             }
             catch (error) {

package/dist/core/migration.d.ts

@@ -5,6 +5,8 @@
  * Called by both init and update commands before profile resolution.
  */
 import { type AIToolOption } from './config.js';
+import { type Delivery, type GlobalConfig, type Profile } from './global-config.js';
+import { type FileView } from './file-view.js';
 export interface LegacyToolRoot {
     /** Former tool root, e.g. '.kimi' */
     root: string;
@@ -41,11 +43,27 @@ export interface LegacyToolMigration {
     /** Whether this move needs the user's consent first */
     needsConsent: boolean;
 }
+/** One file a legacy-root migration would move or drop. */
+export interface LegacyMigrationFileOp {
+    toolId: string;
+    source: string;
+    destination: string;
+    disposition: 'move' | 'drop';
+    /** Whether an interactive run asks before this move */
+    needsConsent: boolean;
+}
 /**
  * Reports the OpenSpec content sitting under each tool's legacy root, without
  * moving anything. Callers use this to ask before a move that needs consent.
  */
 export declare function findLegacyToolMigrations(projectPath: string, timing?: 'before-generation' | 'after-generation'): LegacyToolMigration[];
+/**
+ * Lists, file by file, what `migrateLegacyToolDirs` would move or drop, without
+ * touching anything. Consent-gated roots are included: a non-interactive run
+ * moves them without asking. `view` decides what already sits at each
+ * destination, so a dry run can plan against files it has not written.
+ */
+export declare function planLegacyToolMigrations(projectPath: string, timing: 'before-generation' | 'after-generation', toolIds: string[] | undefined, view: FileView): LegacyMigrationFileOp[];
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
  * (opsx-*) from a tool's legacy root to its current one. When the destination
@@ -81,7 +99,7 @@ export declare function legacyMigrationNotice(migration: LegacyToolMigration): s
  * Scans installed workflow files across all detected tools and returns
  * the union of installed workflow IDs.
  */
-export declare function scanInstalledWorkflows(projectPath: string, tools: AIToolOption[]): string[];
+export declare function scanInstalledWorkflows(projectPath: string, tools: AIToolOption[], view?: FileView): string[];
 /**
  * Performs one-time migration if the global config does not yet have a profile field.
  * Called by both init and update before profile resolution.
@@ -91,5 +109,13 @@ export declare function scanInstalledWorkflows(projectPath: string, tools: AIToo
  * - If no profile field exists and no workflows are installed: no-op (defaults apply).
  * - If profile field already exists: no-op.
  */
+export declare function computeProfileMigration(projectPath: string, tools: AIToolOption[], view?: FileView): ProfileMigration | null;
+export type ProfileMigration = {
+    profile: Profile;
+    workflows: string[];
+    delivery?: Delivery;
+};
+/** The global config the one-time profile migration saves. */
+export declare function applyProfileMigration(migration: ProfileMigration): GlobalConfig;
 export declare function migrateIfNeeded(projectPath: string, tools: AIToolOption[]): void;
 //# sourceMappingURL=migration.d.ts.map

package/dist/core/migration.js

@@ -14,6 +14,7 @@ import { ALL_WORKFLOWS } from './profiles.js';
 import { getSkillReferenceTransformer, getTransformerForTool } from '../utils/command-references.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { isSharedSkillTargetActive } from './shared-skill-target.js';
+import { DISK_VIEW } from './file-view.js';
 import { isLegacyCodexSkillEquivalentToCurrent } from './shared/skill-content-equivalence.js';
 import path from 'path';
 import * as fs from 'fs';
@@ -41,14 +42,14 @@ export const LEGACY_TOOL_ROOTS = {
     // reported and kept rather than overwritten.
     antigravity: [{ root: '.agent', needsConsent: false, timing: 'after-generation' }],
 };
-function classifyManagedFile(source, destination) {
+function classifyManagedFile(source, destination, view = DISK_VIEW) {
     if (isSamePath(source, destination))
         return 'skip';
-    if (!fs.existsSync(destination))
+    if (!view.exists(destination))
         return 'move';
     try {
         const sourceContent = fs.readFileSync(source, 'utf-8');
-        const destinationContent = fs.readFileSync(destination, 'utf-8');
+        const destinationContent = view.read(destination);
         const equivalentGeneratedSkills = path.basename(source) === 'SKILL.md' &&
             path.basename(destination) === 'SKILL.md' &&
             isLegacyCodexSkillEquivalentToCurrent(sourceContent, destinationContent);
@@ -85,6 +86,17 @@ function legacyCommandPath(commandPath, currentRoot, legacyRoot) {
 export function findLegacyToolMigrations(projectPath, timing = 'before-generation') {
     return collectLegacyToolMigrations(projectPath, false, undefined, timing);
 }
+/**
+ * Lists, file by file, what `migrateLegacyToolDirs` would move or drop, without
+ * touching anything. Consent-gated roots are included: a non-interactive run
+ * moves them without asking. `view` decides what already sits at each
+ * destination, so a dry run can plan against files it has not written.
+ */
+export function planLegacyToolMigrations(projectPath, timing, toolIds, view) {
+    const ops = [];
+    collectLegacyToolMigrations(projectPath, false, toolIds, timing, { view, ops });
+    return ops;
+}
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
  * (opsx-*) from a tool's legacy root to its current one. When the destination
@@ -99,7 +111,7 @@ export function findLegacyToolMigrations(projectPath, timing = 'before-generatio
 export function migrateLegacyToolDirs(projectPath, toolIds, timing = 'before-generation') {
     return collectLegacyToolMigrations(projectPath, true, toolIds, timing);
 }
-function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation') {
+function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation', plan) {
     const migrations = [];
     for (const tool of AI_TOOLS) {
         if (!tool.skillsDir)
@@ -126,8 +138,11 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
                 console.warn(`Skipping legacy ${legacy.root}/ migration because the directory resolves outside this project.`);
                 continue;
             }
-            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation');
-            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation');
+            const sink = plan
+                ? { ...plan, toolId: tool.value, needsConsent: legacy.needsConsent }
+                : undefined;
+            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation', sink);
+            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation', sink);
             if (apply) {
                 removeDirIfEmpty(path.join(legacyRootPath, 'skills'));
                 removeDirIfEmpty(path.join(legacyRootPath, 'workflows'));
@@ -152,7 +167,8 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
     }
     return migrations;
 }
-function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false) {
+function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false, sink) {
+    const view = sink?.view ?? DISK_VIEW;
     const legacySkillsDir = path.join(projectPath, legacyRoot, 'skills');
     if (!fs.existsSync(legacySkillsDir))
         return { moved: 0, kept: 0 };
@@ -167,13 +183,13 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
             continue;
         const destination = path.join(currentSkillsDir, dirName);
         const destinationSkill = path.join(destination, 'SKILL.md');
-        if (requireDestination && !fs.existsSync(destinationSkill))
+        if (requireDestination && !view.exists(destinationSkill))
             continue;
         if (!areProjectArtifacts(projectPath, sourceSkill, destinationSkill)) {
             console.warn(`Skipping legacy ${legacyRoot}/skills/${dirName} migration because it resolves outside this project.`);
             continue;
         }
-        const disposition = classifyManagedFile(sourceSkill, destinationSkill);
+        const disposition = classifyManagedFile(sourceSkill, destinationSkill, view);
         if (disposition === 'skip')
             continue;
         if (disposition === 'keep') {
@@ -181,6 +197,13 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
             continue;
         }
         if (!apply) {
+            sink?.ops.push({
+                toolId: sink.toolId,
+                source: sourceSkill,
+                destination: destinationSkill,
+                disposition,
+                needsConsent: sink.needsConsent,
+            });
             moved++;
             continue;
         }
@@ -207,7 +230,8 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
     }
     return { moved, kept };
 }
-function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false) {
+function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false, sink) {
+    const view = sink?.view ?? DISK_VIEW;
     const adapter = CommandAdapterRegistry.get(tool.value);
     if (!adapter || !tool.skillsDir)
         return { moved: 0, kept: 0 };
@@ -226,13 +250,13 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestin
         // No replacement means this command is not one OpenSpec installs now — a
         // skills-only delivery or a deselected workflow — so relocating the legacy
         // file would resurrect it under the current root.
-        if (requireDestination && !fs.existsSync(destination))
+        if (requireDestination && !view.exists(destination))
             continue;
         if (!areProjectArtifacts(projectPath, source, destination)) {
             console.warn(`Skipping legacy ${legacyPath} migration because it resolves outside this project.`);
             continue;
         }
-        const disposition = classifyManagedFile(source, destination);
+        const disposition = classifyManagedFile(source, destination, view);
         if (disposition === 'skip')
             continue;
         if (disposition === 'keep') {
@@ -240,6 +264,13 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestin
             continue;
         }
         if (!apply) {
+            sink?.ops.push({
+                toolId: sink.toolId,
+                source,
+                destination,
+                disposition,
+                needsConsent: sink.needsConsent,
+            });
             moved++;
             continue;
         }
@@ -344,7 +375,7 @@ function removeDirIfEmpty(dirPath) {
         // Missing or non-empty directory — nothing to do
     }
 }
-function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false) {
+function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false, view = DISK_VIEW) {
     const installed = new Set();
     let hasSkills = false;
     let hasCommands = false;
@@ -355,7 +386,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
         if (tool.globalSkillsDir) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
         }
-        else if (isSharedSkillTargetActive(projectPath, tool.value)) {
+        else if (isSharedSkillTargetActive(projectPath, tool.value, view)) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
             if (includeLegacyRoots) {
                 skillsDirs.push(...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectPath, root, 'skills')));
@@ -365,7 +396,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
             for (const workflowId of ALL_WORKFLOWS) {
                 const skillDirName = WORKFLOW_TO_SKILL_DIR[workflowId];
                 const skillFile = path.join(skillsDir, skillDirName, 'SKILL.md');
-                if (fs.existsSync(skillFile)) {
+                if (view.exists(skillFile)) {
                     installed.add(workflowId);
                     hasSkills = true;
                 }
@@ -395,7 +426,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
                 const fullPath = path.isAbsolute(candidate)
                     ? candidate
                     : path.join(projectPath, candidate);
-                if (fs.existsSync(fullPath)) {
+                if (view.exists(fullPath)) {
                     installed.add(workflowId);
                     hasCommands = true;
                     break;
@@ -413,8 +444,8 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
  * Scans installed workflow files across all detected tools and returns
  * the union of installed workflow IDs.
  */
-export function scanInstalledWorkflows(projectPath, tools) {
-    return scanInstalledWorkflowArtifacts(projectPath, tools).workflows;
+export function scanInstalledWorkflows(projectPath, tools, view = DISK_VIEW) {
+    return scanInstalledWorkflowArtifacts(projectPath, tools, false, view).workflows;
 }
 function inferDelivery(artifacts) {
     if (artifacts.hasSkills && artifacts.hasCommands) {
@@ -434,13 +465,12 @@ function inferDelivery(artifacts) {
  * - If no profile field exists and no workflows are installed: no-op (defaults apply).
  * - If profile field already exists: no-op.
  */
-export function migrateIfNeeded(projectPath, tools) {
+export function computeProfileMigration(projectPath, tools, view = DISK_VIEW) {
     // A config that cannot be parsed, or is not a JSON object, is never saved
     // over; skip migration rather than fail init or update on it.
     if (isGlobalConfigUnreadable()) {
-        return;
+        return null;
     }
-    const config = getGlobalConfig();
     // Check raw config file for profile field presence
     const configPath = getGlobalConfigPath();
     let rawConfig = {};
@@ -450,25 +480,43 @@ export function migrateIfNeeded(projectPath, tools) {
         }
     }
     catch {
-        return; // Can't read config, skip migration
+        return null; // Can't read config, skip migration
     }
     // If profile is already explicitly set, no migration needed
     if (rawConfig.profile !== undefined) {
-        return;
+        return null;
     }
     // Scan for installed workflows
-    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true);
+    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true, view);
     const installedWorkflows = artifacts.workflows;
     if (installedWorkflows.length === 0) {
         // No workflows installed, new user — defaults will apply
-        return;
+        return null;
     }
+    return {
+        profile: 'custom',
+        workflows: installedWorkflows,
+        ...(rawConfig.delivery === undefined ? { delivery: inferDelivery(artifacts) } : {}),
+    };
+}
+/** The global config the one-time profile migration saves. */
+export function applyProfileMigration(migration) {
+    const config = getGlobalConfig();
     // Migrate: set profile to custom with detected workflows
-    config.profile = 'custom';
-    config.workflows = installedWorkflows;
-    if (rawConfig.delivery === undefined) {
-        config.delivery = inferDelivery(artifacts);
+    config.profile = migration.profile;
+    config.workflows = migration.workflows;
+    if (migration.delivery !== undefined) {
+        config.delivery = migration.delivery;
+    }
+    return config;
+}
+export function migrateIfNeeded(projectPath, tools) {
+    const migration = computeProfileMigration(projectPath, tools);
+    if (!migration) {
+        return;
     }
+    const config = applyProfileMigration(migration);
+    const installedWorkflows = migration.workflows;
     saveGlobalConfig(config);
     console.log(`Migrated: custom profile with ${installedWorkflows.length} workflows`);
     // Each detected tool resolves to a propose reference for its surface: the

package/dist/core/profile-sync-drift.d.ts

@@ -1,5 +1,6 @@
 import type { Delivery } from './global-config.js';
 import { ALL_WORKFLOWS } from './profiles.js';
+import { type FileView } from './file-view.js';
 type WorkflowId = (typeof ALL_WORKFLOWS)[number];
 /**
  * Maps workflow IDs to their skill directory names.
@@ -8,7 +9,7 @@ export declare const WORKFLOW_TO_SKILL_DIR: Record<WorkflowId, string>;
 /**
  * Returns tools that are configured via either skills or commands.
  */
-export declare function getConfiguredToolsForProfileSync(projectPath: string): string[];
+export declare function getConfiguredToolsForProfileSync(projectPath: string, view?: FileView): string[];
 /**
  * Detects if a single tool has profile/delivery drift against the desired state.
  *
@@ -17,11 +18,11 @@ export declare function getConfiguredToolsForProfileSync(projectPath: string): s
  * - artifacts that should not exist for the selected delivery mode
  * - artifacts for workflows that were deselected from the current profile
  */
-export declare function hasToolProfileOrDeliveryDrift(projectPath: string, toolId: string, desiredWorkflows: readonly string[], delivery: Delivery): boolean;
+export declare function hasToolProfileOrDeliveryDrift(projectPath: string, toolId: string, desiredWorkflows: readonly string[], delivery: Delivery, view?: FileView): boolean;
 /**
  * Returns configured tools that currently need a profile/delivery sync.
  */
-export declare function getToolsNeedingProfileSync(projectPath: string, desiredWorkflows: readonly string[], delivery: Delivery, configuredTools?: readonly string[]): string[];
+export declare function getToolsNeedingProfileSync(projectPath: string, desiredWorkflows: readonly string[], delivery: Delivery, configuredTools?: readonly string[], view?: FileView): string[];
 /**
  * Detects whether the current project has any profile/delivery drift.
  */