@fission-ai/openspec 1.11.0 → 1.13.0

package/dist/core/init.d.ts

@@ -78,6 +78,7 @@ export declare class InitCommand {
     private resolveToolsArg;
     private validateTools;
     private createDirectoryStructure;
+    private writeGitkeepFiles;
     /**
      * Generates skill files and slash commands for each selected tool,
      * honoring the configured delivery mode (skills, commands, or both).

package/dist/core/init.js

@@ -12,6 +12,7 @@ import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { classifyOpenSpecDir, MAX_CONTEXT_SIZE, readProjectConfig, storePointerProblem, } from './project-config.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
+import { ANCHORED_OPENSPEC_DIRS, ensureDirectoryAnchor } from './openspec-root.js';
 import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
 import { PALETTE } from './styles/palette.js';
@@ -19,10 +20,11 @@ import { isInteractive } from '../utils/interactive.js';
 import { serializeConfig } from './config-prompts.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDeferredGlobalPromptSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
-import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
+import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
+import { formatOptionalWorkflowsNote } from './onboarding-commands.js';
 import { resolveSharedSkillWriters, sharedSkillRootOwner, writeSharedSkillTarget, } from './shared-skill-target.js';
 import { migrateIfNeeded, migrateLegacyToolDirs, describeLegacyMigration, keptInPlaceNotice, hasMovableContent, scanInstalledWorkflows as scanInstalledWorkflowsShared } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
@@ -590,7 +592,6 @@ export class InitCommand {
                 skillsRoot: isGlobalSkillTarget ? skillsPath : projectPath,
                 isGlobalSkillTarget,
                 wasConfigured: preState?.configured ?? false,
-                requiresIdeRestart: tool.requiresIdeRestart,
                 writesSkills: !tool.skillsDir || skillWriters.has(tool.value),
             });
         }
@@ -600,36 +601,37 @@ export class InitCommand {
     // DIRECTORY STRUCTURE
     // ═══════════════════════════════════════════════════════════
     async createDirectoryStructure(openspecPath, extendMode) {
+        const directories = [
+            openspecPath,
+            path.join(openspecPath, 'specs'),
+            path.join(openspecPath, 'changes'),
+            path.join(openspecPath, 'changes', 'archive'),
+        ];
         if (extendMode) {
             // In extend mode, just ensure directories exist without spinner
-            const directories = [
-                openspecPath,
-                path.join(openspecPath, 'specs'),
-                path.join(openspecPath, 'changes'),
-                path.join(openspecPath, 'changes', 'archive'),
-            ];
             for (const dir of directories) {
                 FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), dir);
                 await FileSystemUtils.createDirectory(dir);
             }
+            await this.writeGitkeepFiles(openspecPath);
             return;
         }
         const spinner = this.startSpinner('Creating OpenSpec structure...');
-        const directories = [
-            openspecPath,
-            path.join(openspecPath, 'specs'),
-            path.join(openspecPath, 'changes'),
-            path.join(openspecPath, 'changes', 'archive'),
-        ];
         for (const dir of directories) {
             FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), dir);
             await FileSystemUtils.createDirectory(dir);
         }
+        await this.writeGitkeepFiles(openspecPath);
         spinner.stopAndPersist({
             symbol: PALETTE.white('▌'),
             text: PALETTE.white('OpenSpec structure created'),
         });
     }
+    async writeGitkeepFiles(openspecPath) {
+        for (const relativeDir of ANCHORED_OPENSPEC_DIRS) {
+            await ensureDirectoryAnchor(path.dirname(openspecPath), relativeDir);
+        }
+    }
     // ═══════════════════════════════════════════════════════════
     // SKILL & COMMAND GENERATION
     // ═══════════════════════════════════════════════════════════
@@ -1017,9 +1019,11 @@ export class InitCommand {
                 `${zeroArtifactTools.length === 1 ? 'it supports' : 'they support'} only skills. ` +
                 `Run 'openspec config set delivery both' to generate skills.`));
         }
+        let advertisedAnInvocation = true;
         if (successfulTools.length > 0 && !commandsGenerated && !skillsGenerated) {
             // Nothing was generated for any tool: the correction above is the
             // whole story, so don't advertise an invocation that doesn't exist.
+            advertisedAnInvocation = false;
         }
         else if (activeWorkflows.includes('propose')) {
             printStartHints('/opsx:propose');
@@ -1029,32 +1033,35 @@ export class InitCommand {
         }
         else {
             console.log("Done. Run 'openspec config profile' to configure your workflows.");
+            advertisedAnInvocation = false;
+        }
+        // Workflows the active profile left out. Setup is the only moment a user
+        // is told what exists, so name them here rather than let a missing
+        // command read as a broken install (#1076). Skipped when the branch above
+        // already pointed at `openspec config profile`, and when no tool received
+        // a workflow surface at all (no tools selected, or none that could take
+        // one) — there, adding workflows writes nothing, so naming them would
+        // point at the wrong problem.
+        if (advertisedAnInvocation && (commandsGenerated || skillsGenerated)) {
+            const optionalWorkflowsNote = formatOptionalWorkflowsNote(activeWorkflows);
+            if (optionalWorkflowsNote) {
+                console.log();
+                for (const line of optionalWorkflowsNote) {
+                    console.log(chalk.dim(line));
+                }
+            }
         }
         // Links
         console.log();
         console.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
         console.log(`Feedback:   ${chalk.cyan('https://github.com/Fission-AI/OpenSpec/issues')}`);
-        // Restart instruction only when at least one IDE/editor-resident tool
-        // actually received a generated surface. Two conditions, coupled to the SAME
-        // tool: (1) its commands/skills are loaded by a long-running editor process
-        // (CLI tools pick the files up immediately, so a restart line would be wrong
-        // for them — see #1067), and (2) a surface was actually generated for it
-        // under the active delivery (an IDE tool that generated nothing has nothing a
-        // restart would pick up, even if a co-configured CLI tool did generate).
-        // Wording follows what the IDE tool itself generated, not the global
-        // aggregate: it must not say "commands" when the IDE tool only got skills
-        // while a co-configured CLI tool got commands. Not "slash commands" either:
-        // Amazon Q's generated files are prompt-library entries invoked with @, so a
-        // restart line promising slash commands would be wrong for it.
-        const restartCommandsGenerated = successfulTools.some((tool) => tool.requiresIdeRestart &&
-            shouldGenerateCommandsForTool(tool.value, activeDelivery));
-        const restartSkillsGenerated = successfulTools.some((tool) => tool.requiresIdeRestart &&
-            shouldGenerateSkillsForTool(tool.value, activeDelivery));
-        if (restartCommandsGenerated || restartSkillsGenerated) {
+        // Restart instruction for successfully configured IDE/editor-resident tools
+        // with a supported surface under the active delivery. The rule and wording live in
+        // formatIdeRestart so `update` says the same thing for the same event.
+        const restartHint = formatIdeRestart(successfulTools.map((tool) => tool.value), activeDelivery);
+        if (restartHint) {
             console.log();
-            console.log(chalk.white(restartCommandsGenerated
-                ? 'Restart your IDE for the new commands to take effect.'
-                : 'Restart your IDE for the new skills to take effect.'));
+            console.log(chalk.white(restartHint));
         }
         console.log();
     }

package/dist/core/onboarding-commands.d.ts

@@ -9,7 +9,7 @@
  * tool — command, skill, or a tool-specific skill prefix — is decided by
  * src/utils/command-references.ts at the call site.
  */
-import type { WorkflowId } from './profiles.js';
+import { type WorkflowId } from './profiles.js';
 export type OnboardingCommand = {
     workflow: WorkflowId;
     command: string;
@@ -27,4 +27,14 @@ export declare const DESCRIPTION_BUDGET = 17;
  * Returns an empty array when none of the onboarding workflows are installed.
  */
 export declare function getOnboardingCommands(workflows: readonly string[]): OnboardingCommand[];
+/**
+ * Returns the note telling a user which workflows their profile left out, or
+ * null when every workflow is already installed.
+ *
+ * Setup output otherwise never names the workflows that exist but were not
+ * installed, so a user on the default profile has no way to learn that
+ * `/opsx:ff` and friends are one command away. The docs say it; nobody reads
+ * the docs before typing a command that isn't there.
+ */
+export declare function formatOptionalWorkflowsNote(installedWorkflows: readonly string[]): string[] | null;
 //# sourceMappingURL=onboarding-commands.d.ts.map

package/dist/core/onboarding-commands.js

@@ -9,6 +9,7 @@
  * tool — command, skill, or a tool-specific skill prefix — is decided by
  * src/utils/command-references.ts at the call site.
  */
+import { ALL_WORKFLOWS } from './profiles.js';
 /**
  * Longest description the welcome screen can render. It shows these beside a
  * 24-column art column and only animates at MIN_WIDTH (60) columns or wider; a
@@ -35,4 +36,29 @@ export function getOnboardingCommands(workflows) {
     const installed = new Set(workflows);
     return ONBOARDING_COMMANDS.filter((entry) => installed.has(entry.workflow));
 }
+/**
+ * Returns the note telling a user which workflows their profile left out, or
+ * null when every workflow is already installed.
+ *
+ * Setup output otherwise never names the workflows that exist but were not
+ * installed, so a user on the default profile has no way to learn that
+ * `/opsx:ff` and friends are one command away. The docs say it; nobody reads
+ * the docs before typing a command that isn't there.
+ */
+export function formatOptionalWorkflowsNote(installedWorkflows) {
+    const installed = new Set(installedWorkflows);
+    const missing = ALL_WORKFLOWS.filter((workflow) => !installed.has(workflow));
+    if (missing.length === 0) {
+        return null;
+    }
+    const label = missing.length === 1 ? 'workflow is' : 'workflows are';
+    const pronoun = missing.length === 1 ? 'it' : 'them';
+    // `openspec config profile` offers to apply to this project before it
+    // exits, and prints the `openspec update` guidance itself when declined, so
+    // naming a second command here would be one step too many.
+    return [
+        `Note: ${missing.length} more ${label} available (${missing.join(', ')}).`,
+        `Add ${pronoun} with \`openspec config profile\`.`,
+    ];
+}
 //# sourceMappingURL=onboarding-commands.js.map

package/dist/core/openspec-root.d.ts

@@ -37,6 +37,7 @@ export interface EnsureOpenSpecRootResult {
     createdPaths: CreatedPathLedgerEntry[];
 }
 export declare function inspectOpenSpecRoot(storeRoot: string): Promise<OpenSpecRootInspection>;
+export declare function ensureDirectoryAnchor(storeRoot: string, relativeDir: string, ledger?: CreatedPathLedgerEntry[]): Promise<void>;
 export interface EnsureOpenSpecRootOptions {
     anchorEmptyDirectories?: boolean;
 }

package/dist/core/openspec-root.js

@@ -144,13 +144,21 @@ async function ensureDefaultConfig(storeRoot, ledger) {
         kind: 'file',
     });
 }
-async function ensureDirectoryAnchor(storeRoot, relativeDir, ledger) {
+export async function ensureDirectoryAnchor(storeRoot, relativeDir, ledger = []) {
     const directory = path.join(storeRoot, relativeDir);
     if ((await fs.readdir(directory)).length > 0)
         return;
     const relativePath = `${relativeDir}/${DIRECTORY_ANCHOR_FILE_NAME}`;
     const absolutePath = path.join(directory, DIRECTORY_ANCHOR_FILE_NAME);
-    await fs.writeFile(absolutePath, '', 'utf-8');
+    try {
+        // A file or symlink may appear after readdir. Never replace or follow it.
+        await fs.writeFile(absolutePath, '', { encoding: 'utf-8', flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return;
+        throw error;
+    }
     ledger.push({
         relativePath: relativeArtifact(relativePath, 'file'),
         absolutePath,

package/dist/core/parsers/requirement-blocks.js

@@ -99,24 +99,26 @@ export function parseDeltaSpec(content) {
     const lines = normalized.split('\n');
     const fenceMask = buildCodeFenceMask(lines);
     const sections = splitTopLevelSections(lines, fenceMask);
-    const addedLookup = getSectionCaseInsensitive(sections, 'ADDED Requirements');
-    const modifiedLookup = getSectionCaseInsensitive(sections, 'MODIFIED Requirements');
-    const removedLookup = getSectionCaseInsensitive(sections, 'REMOVED Requirements');
-    const renamedLookup = getSectionCaseInsensitive(sections, 'RENAMED Requirements');
+    const addedLookup = getSectionsCaseInsensitive(sections, 'ADDED Requirements');
+    const modifiedLookup = getSectionsCaseInsensitive(sections, 'MODIFIED Requirements');
+    const removedLookup = getSectionsCaseInsensitive(sections, 'REMOVED Requirements');
+    const renamedLookup = getSectionsCaseInsensitive(sections, 'RENAMED Requirements');
     const skippedHeaders = [];
-    const added = parseRequirementBlocksFromSection(addedLookup.body, {
+    const added = addedLookup.bodies.flatMap((body) => parseRequirementBlocksFromSection(body, {
         section: addedLookup.title,
-        bodyStartLine: addedLookup.bodyStartLine,
+        bodyStartLine: body.bodyStartLine,
         sink: skippedHeaders,
-    });
-    const modified = parseRequirementBlocksFromSection(modifiedLookup.body, {
+    }));
+    const modified = modifiedLookup.bodies.flatMap((body) => parseRequirementBlocksFromSection(body, {
         section: modifiedLookup.title,
-        bodyStartLine: modifiedLookup.bodyStartLine,
+        bodyStartLine: body.bodyStartLine,
         sink: skippedHeaders,
-    });
-    const removedNames = parseRemovedNames(removedLookup.body);
-    const removedBlocks = parseRequirementBlocksFromSection(removedLookup.body);
-    const renamedPairs = parseRenamedPairs(renamedLookup.body);
+    }));
+    const removedNames = removedLookup.bodies.flatMap((body) => parseRemovedNames(body));
+    const removedBlocks = removedLookup.bodies.flatMap((body) => parseRequirementBlocksFromSection(body));
+    // Pairs are read per section, so a FROM in one copy of the header can never
+    // pair with a TO in another.
+    const renamedPairs = renamedLookup.bodies.flatMap((body) => parseRenamedPairs(body));
     skippedHeaders.sort((a, b) => a.line - b.line);
     return {
         added,
@@ -133,8 +135,16 @@ export function parseDeltaSpec(content) {
         },
     };
 }
+/**
+ * Every `## ` section, as a LIST rather than a title-keyed record.
+ *
+ * Keying by title silently dropped a repeated header: a delta that wrote
+ * `## ADDED Requirements` twice kept only the last body, so every requirement
+ * under the first copy was discarded before any validation or merge rule could
+ * see it. A list keeps each occurrence, and the lookup below merges them.
+ */
 function splitTopLevelSections(lines, fenceMask) {
-    const result = {};
+    const sections = [];
     const indices = [];
     for (let i = 0; i < lines.length; i++) {
         if (fenceMask[i])
@@ -148,23 +158,39 @@ function splitTopLevelSections(lines, fenceMask) {
         const current = indices[i];
         const next = indices[i + 1];
         const end = next ? next.index : lines.length;
-        result[current.title] = {
-            lines: lines.slice(current.index + 1, end),
-            fenceMask: fenceMask.slice(current.index + 1, end),
-            bodyStartLine: current.index + 2,
-        };
+        sections.push({
+            title: current.title,
+            body: {
+                lines: lines.slice(current.index + 1, end),
+                fenceMask: fenceMask.slice(current.index + 1, end),
+                bodyStartLine: current.index + 2,
+            },
+        });
     }
-    return result;
+    return sections;
 }
-const EMPTY_SECTION_BODY = { lines: [], fenceMask: [], bodyStartLine: 0 };
-function getSectionCaseInsensitive(sections, desired) {
+/**
+ * Every section body whose title folds to `desired`, in document order.
+ *
+ * Returning all of them - rather than the first match - is what makes a
+ * repeated header (`## ADDED Requirements` twice) and a case variant
+ * (`## ADDED Requirements` + `## Added Requirements`) both apply in full. Each
+ * body keeps its own `bodyStartLine`, so reported line numbers stay correct for
+ * the copy the header actually came from.
+ *
+ * `title` is the first spelling the author used, which is what diagnostics quote.
+ */
+function getSectionsCaseInsensitive(sections, desired) {
     const target = desired.toLowerCase();
-    for (const [title, body] of Object.entries(sections)) {
-        if (title.toLowerCase() === target) {
-            return { title, body, bodyStartLine: body.bodyStartLine, found: true };
-        }
+    const matches = sections.filter((section) => section.title.toLowerCase() === target);
+    if (matches.length === 0) {
+        return { title: desired, bodies: [], found: false };
     }
-    return { title: desired, body: EMPTY_SECTION_BODY, bodyStartLine: 0, found: false };
+    return {
+        title: matches[0].title,
+        bodies: matches.map((section) => section.body),
+        found: true,
+    };
 }
 function parseRequirementBlocksFromSection(sectionBody, skipped) {
     const { lines, fenceMask } = sectionBody;
@@ -212,6 +238,13 @@ function parseRequirementBlocksFromSection(sectionBody, skipped) {
     }
     return blocks;
 }
+/**
+ * Requirement names listed in `## REMOVED Requirements`, in document order.
+ *
+ * Two spellings are accepted: a plain `### Requirement:` header, and a bullet
+ * carrying one. Every CommonMark bullet marker counts for the second form -
+ * see the pattern below for why that matters.
+ */
 function parseRemovedNames(sectionBody) {
     const { lines, fenceMask } = sectionBody;
     if (lines.length === 0)
@@ -226,14 +259,24 @@ function parseRemovedNames(sectionBody) {
             names.push(normalizeRequirementName(m[1]));
             continue;
         }
-        // Also support bullet list of headers
-        const bullet = line.match(/^\s*-\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+        // Also support bullet list of headers. Every CommonMark bullet marker
+        // counts: `*` and `+` open a list exactly as `-` does, so accepting only
+        // `-` turned a removal written with either of them into a silent no-op -
+        // archive reported success while the requirement stayed in the spec.
+        const bullet = line.match(/^\s*[-*+]\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
         if (bullet) {
             names.push(normalizeRequirementName(bullet[1]));
         }
     }
     return names;
 }
+/**
+ * `FROM:`/`TO:` rename pairs from `## RENAMED Requirements`, in document order.
+ *
+ * The bullet is optional, and every CommonMark bullet marker is accepted: a
+ * rename written with `*` or `+` used to match nothing at all, so the rename
+ * silently never happened while archive still reported success.
+ */
 function parseRenamedPairs(sectionBody) {
     const { lines, fenceMask } = sectionBody;
     if (lines.length === 0)
@@ -244,8 +287,11 @@ function parseRenamedPairs(sectionBody) {
         if (fenceMask[i])
             continue;
         const line = lines[i];
-        const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
-        const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+        // The bullet stays optional, and any CommonMark marker is accepted: a rename
+        // written with `*` or `+` used to match nothing at all, so the rename never
+        // happened while archive still reported success.
+        const fromMatch = line.match(/^\s*[-*+]?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+        const toMatch = line.match(/^\s*[-*+]?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
         if (fromMatch) {
             current.from = normalizeRequirementName(fromMatch[1]);
         }

package/dist/core/shared/ide-restart.d.ts

@@ -0,0 +1,26 @@
+/**
+ * IDE restart hint
+ *
+ * Shared restart guidance for tools successfully configured by init or update.
+ * The wording covers additions, updates, and removals, including an empty
+ * workflow selection that removes every generated file.
+ */
+import type { Delivery } from '../global-config.js';
+/** The surface a restart hint names. Absent when no hint is due. */
+export type IdeRestartSurface = 'commands' | 'skills';
+/**
+ * Both conditions stay coupled to the SAME tool: its surfaces are loaded by a
+ * long-running editor process (a CLI picks them up immediately, so a restart
+ * line would be wrong for it — see #1067), and it supports a generated surface
+ * under the active delivery. A CLI tool's commands must not determine the hint
+ * for an IDE tool that only supports skills. Commands take precedence when
+ * both surfaces are supported under the active delivery.
+ */
+export declare function resolveIdeRestartSurface(toolIds: readonly string[], delivery: Delivery): IdeRestartSurface | null;
+/**
+ * The restart line to print, or null when no restart is needed. Deliberately
+ * not "slash commands": Amazon Q's generated files are prompt-library entries
+ * invoked with `@`, so promising slash commands would be wrong for it.
+ */
+export declare function formatIdeRestart(toolIds: readonly string[], delivery: Delivery): string | null;
+//# sourceMappingURL=ide-restart.d.ts.map

package/dist/core/shared/ide-restart.js

@@ -0,0 +1,42 @@
+/**
+ * IDE restart hint
+ *
+ * Shared restart guidance for tools successfully configured by init or update.
+ * The wording covers additions, updates, and removals, including an empty
+ * workflow selection that removes every generated file.
+ */
+import { AI_TOOLS } from '../config.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, } from '../command-surface.js';
+function isIdeResident(toolId) {
+    return Boolean(AI_TOOLS.find((tool) => tool.value === toolId)?.requiresIdeRestart);
+}
+/**
+ * Both conditions stay coupled to the SAME tool: its surfaces are loaded by a
+ * long-running editor process (a CLI picks them up immediately, so a restart
+ * line would be wrong for it — see #1067), and it supports a generated surface
+ * under the active delivery. A CLI tool's commands must not determine the hint
+ * for an IDE tool that only supports skills. Commands take precedence when
+ * both surfaces are supported under the active delivery.
+ */
+export function resolveIdeRestartSurface(toolIds, delivery) {
+    const ideTools = [...new Set(toolIds)].filter(isIdeResident);
+    if (ideTools.some((toolId) => shouldGenerateCommandsForTool(toolId, delivery))) {
+        return 'commands';
+    }
+    if (ideTools.some((toolId) => shouldGenerateSkillsForTool(toolId, delivery))) {
+        return 'skills';
+    }
+    return null;
+}
+/**
+ * The restart line to print, or null when no restart is needed. Deliberately
+ * not "slash commands": Amazon Q's generated files are prompt-library entries
+ * invoked with `@`, so promising slash commands would be wrong for it.
+ */
+export function formatIdeRestart(toolIds, delivery) {
+    const surface = resolveIdeRestartSurface(toolIds, delivery);
+    return surface
+        ? `Restart your IDE to refresh ${surface}.`
+        : null;
+}
+//# sourceMappingURL=ide-restart.js.map

package/dist/core/shared/index.d.ts

@@ -6,4 +6,5 @@
 export { SKILL_NAMES, type SkillName, COMMAND_IDS, type CommandId, type ToolSkillStatus, type ToolVersionStatus, getToolsWithSkillsDir, getToolSkillStatus, getToolStates, extractGeneratedByVersion, getToolVersionStatus, getConfiguredTools, getAllToolVersionStatus, } from './tool-detection.js';
 export { type SkillTemplateEntry, type CommandTemplateEntry, getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
 export { type SkillCapableTool, toolSupportsSkills, getSkillCapableTools, hasGlobalSkillTarget, resolveToolSkillsDir, } from './skill-paths.js';
+export { type IdeRestartSurface, resolveIdeRestartSurface, formatIdeRestart, } from './ide-restart.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/shared/index.js

@@ -6,4 +6,5 @@
 export { SKILL_NAMES, COMMAND_IDS, getToolsWithSkillsDir, getToolSkillStatus, getToolStates, extractGeneratedByVersion, getToolVersionStatus, getConfiguredTools, getAllToolVersionStatus, } from './tool-detection.js';
 export { getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
 export { toolSupportsSkills, getSkillCapableTools, hasGlobalSkillTarget, resolveToolSkillsDir, } from './skill-paths.js';
+export { resolveIdeRestartSurface, formatIdeRestart, } from './ide-restart.js';
 //# sourceMappingURL=index.js.map

package/dist/core/shared/tool-detection.js

@@ -253,7 +253,34 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
             generatedByVersion = currentVersion;
         }
     }
-    const needsUpdate = configured && (generatedByVersion === null || generatedByVersion !== currentVersion);
+    // 3. A version marker in a skill file only proves the SKILL files came from
+    //    this CLI. It says nothing about the command files written beside them,
+    //    which a user may have hand-edited or a partial write may have truncated.
+    //    Without this, `update` answered "all tools up to date" while a damaged
+    //    command file sat on disk, repairable only by knowing to pass --force.
+    //    The content comparison already exists; it was simply never consulted
+    //    once a skill file supplied a version.
+    //
+    //    Scoped to tools that have BOTH, so the commands-only path above keeps
+    //    its exact behaviour, and skipped when the delivery mode generates no
+    //    commands for this tool - there would be nothing to compare against, and
+    //    `areCommandFilesUpToDate` reports an empty command set as "not current".
+    let commandsDrifted = false;
+    if (skillConfigured && commandConfigured) {
+        let generatesCommands = true;
+        try {
+            generatesCommands = shouldGenerateCommandsForTool(toolId, getGlobalConfig().delivery ?? 'both');
+        }
+        catch {
+            generatesCommands = true;
+        }
+        commandsDrifted =
+            generatesCommands && !areCommandFilesUpToDate(projectRoot, toolId, options);
+    }
+    const needsUpdate = configured &&
+        (generatedByVersion === null ||
+            generatedByVersion !== currentVersion ||
+            commandsDrifted);
     return {
         toolId,
         toolName: tool.name,