@fission-ai/openspec 1.12.0 → 1.13.1

package/dist/core/legacy-cleanup.js

@@ -22,19 +22,26 @@ export const LEGACY_CONFIG_FILES = [
     'AGENTS.md', // root AGENTS.md (not openspec/AGENTS.md)
     'QWEN.md',
 ];
+/** The three commands the old SlashCommandRegistry wrote into each directory. */
+const LEGACY_DIRECTORY_COMMAND_FILES = ['proposal.md', 'apply.md', 'archive.md'];
 /**
  * Legacy slash command patterns from the old SlashCommandRegistry.
  * These map toolId to the path pattern where legacy commands were created.
  * Some tools used a directory structure, others used individual files.
  */
 export const LEGACY_SLASH_COMMAND_PATHS = {
-    // Directory-based: .tooldir/commands/openspec/ or .tooldir/commands/openspec/*.md
-    'claude': { type: 'directory', path: '.claude/commands/openspec' },
-    'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec' },
-    'qoder': { type: 'directory', path: '.qoder/commands/openspec' },
-    'lingma': { type: 'directory', path: '.lingma/commands/openspec' },
-    'crush': { type: 'directory', path: '.crush/commands/openspec' },
-    'gemini': { type: 'directory', path: '.gemini/commands/openspec' },
+    // Directory-based: .tooldir/commands/openspec/. Each entry names the files
+    // OpenSpec wrote there, because users keep their own commands in the same
+    // folder: only those files are deleted, and the folder only once it is empty.
+    'claude': { type: 'directory', path: '.claude/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    'qoder': { type: 'directory', path: '.qoder/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    // Lingma support arrived after the opsx rename and has always written to
+    // `.lingma/commands/opsx/`, so OpenSpec never put a file here: only an empty
+    // leftover folder is removed.
+    'lingma': { type: 'directory', path: '.lingma/commands/openspec', managedFileNames: [] },
+    'crush': { type: 'directory', path: '.crush/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    'gemini': { type: 'directory', path: '.gemini/commands/openspec', managedFileNames: ['proposal.toml', 'apply.toml', 'archive.toml'] },
     // File-based: individual openspec-*.md files in a commands/workflows/prompts folder
     'cursor': { type: 'files', pattern: '.cursor/commands/openspec-*.md' },
     // Keyed by the tool id these map back to, so the pre-opsx Windsurf files
@@ -221,9 +228,22 @@ export async function detectLegacySlashCommands(projectPath) {
     for (const pattern of Object.values(LEGACY_SLASH_COMMAND_PATHS)) {
         if (pattern.type === 'directory' && pattern.path) {
             const dirPath = FileSystemUtils.joinPath(projectPath, pattern.path);
-            if (await FileSystemUtils.directoryExists(dirPath)) {
+            if (!(await FileSystemUtils.directoryExists(dirPath))) {
+                continue;
+            }
+            const entries = await readLegacyCommandDir(dirPath, pattern.managedFileNames ?? []);
+            if (!entries) {
+                continue;
+            }
+            if (entries.others.length === 0) {
+                // Only OpenSpec's own files, or nothing: the whole folder can go.
                 directories.push(pattern.path);
             }
+            else {
+                // The folder also holds the user's files, so report OpenSpec's files
+                // one by one; cleanup deletes those and leaves the folder in place.
+                files.push(...entries.managed.map((name) => `${pattern.path}/${name}`));
+            }
         }
         else if (pattern.type === 'files' && pattern.pattern) {
             const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
@@ -235,6 +255,92 @@ export async function detectLegacySlashCommands(projectPath) {
     }
     return { directories, files };
 }
+/**
+ * Splits a legacy command directory's entries into the files OpenSpec wrote
+ * there and everything else, sorted. A file counts as OpenSpec's only when it
+ * is a regular file with a managed name whose content still carries the
+ * OpenSpec markers every legacy command was written with; a folder, a link, or
+ * a same-named file the user wrote is the user's. Subdirectories are listed
+ * with a trailing '/'. Returns undefined when the directory cannot be read or
+ * is itself a symlink, which is never followed.
+ */
+async function readLegacyCommandDir(dirPath, managedFileNames) {
+    let entries;
+    try {
+        if ((await fs.lstat(dirPath)).isSymbolicLink()) {
+            return undefined;
+        }
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    const managed = [];
+    const others = [];
+    for (const entry of entries) {
+        if (entry.isFile() &&
+            managedFileNames.includes(entry.name) &&
+            (await isGeneratedLegacyCommand(path.join(dirPath, entry.name)))) {
+            managed.push(entry.name);
+        }
+        else {
+            others.push(entry.isDirectory() ? `${entry.name}/` : entry.name);
+        }
+    }
+    return { managed: managed.sort(), others: others.sort() };
+}
+/**
+ * The legacy command directory, and its tool, that a repo-local path is one of
+ * OpenSpec's own files in.
+ */
+function legacyCommandDirForFile(file) {
+    const normalizedFile = normalizePathForMatch(file);
+    for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
+        if (pattern.type !== 'directory' || !pattern.path)
+            continue;
+        const dir = pattern.path;
+        if (pattern.managedFileNames?.some((name) => normalizedFile === `${dir}/${name}`)) {
+            return { toolId, dir };
+        }
+    }
+    return undefined;
+}
+/**
+ * Removes a legacy command directory once OpenSpec's files are gone from it,
+ * 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) {
+    const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
+    const remaining = await readLegacyCommandDir(fullPath, []);
+    if (!remaining) {
+        return false;
+    }
+    if (remaining.others.length === 0) {
+        await fs.rmdir(fullPath);
+        result.deletedDirs.push(dirPath);
+        return true;
+    }
+    result.keptFiles.push(...remaining.others.map((name) => `${dirPath}/${name}`));
+    return false;
+}
+/**
+ * Whether a file is a legacy command OpenSpec generated: a regular file (not a
+ * link) whose content carries the OpenSpec markers. Every legacy slash command
+ * was written with them, and OpenSpec refused to update one that lost them, so
+ * a same-named file without them is the user's.
+ */
+async function isGeneratedLegacyCommand(filePath) {
+    try {
+        if (!(await fs.lstat(filePath)).isFile()) {
+            return false;
+        }
+        return hasOpenSpecMarkers(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Detects legacy global slash command files.
  *
@@ -376,6 +482,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
         deletedFileReplacementLabels: {},
         modifiedFiles: [],
         deletedDirs: [],
+        keptFiles: [],
         projectMdNeedsMigration: detection.hasProjectMd,
         errors: [],
     };
@@ -394,21 +501,50 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             result.errors.push(`Failed to modify ${fileName}: ${error.message}`);
         }
     }
-    // Delete legacy slash command directories (these are 100% OpenSpec-managed)
+    // Delete legacy slash command directories: only the files OpenSpec wrote,
+    // then the directory once it is empty. Detection reports a directory only
+    // when it holds nothing else, but a file the user added since is still kept.
     for (const dirPath of detection.slashCommandDirs) {
         const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
         try {
-            await fs.rm(fullPath, { recursive: true, force: true });
-            result.deletedDirs.push(dirPath);
+            const managedFileNames = legacyManagedFileNamesForDir(dirPath);
+            const entries = await readLegacyCommandDir(fullPath, managedFileNames);
+            if (!entries) {
+                continue;
+            }
+            const deleted = [];
+            for (const name of entries.managed) {
+                const filePath = path.join(fullPath, name);
+                // Check again just before deleting: the file may have been replaced
+                // with the user's own since the scan. A kept file is reported below.
+                if (!(await isGeneratedLegacyCommand(filePath))) {
+                    continue;
+                }
+                await fs.unlink(filePath);
+                deleted.push(name);
+            }
+            if (!(await settleLegacyCommandDir(projectPath, dirPath, result))) {
+                result.deletedFiles.push(...deleted.map((name) => `${dirPath}/${name}`));
+            }
         }
         catch (error) {
             result.errors.push(`Failed to delete directory ${dirPath}: ${error.message}`);
         }
     }
     // Delete legacy slash command files (these are 100% OpenSpec-managed)
+    const partlyCleanedDirs = new Set();
     for (const filePath of detection.slashCommandFiles) {
         const fullPath = FileSystemUtils.joinPath(projectPath, filePath);
         try {
+            const commandDir = legacyCommandDirForFile(filePath);
+            if (commandDir) {
+                partlyCleanedDirs.add(commandDir.dir);
+                // Check again just before deleting: the file may have been replaced
+                // with the user's own since detection. A kept file is reported below.
+                if (!(await isGeneratedLegacyCommand(fullPath))) {
+                    continue;
+                }
+            }
             await fs.unlink(fullPath);
             result.deletedFiles.push(filePath);
         }
@@ -416,6 +552,16 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             result.errors.push(`Failed to delete ${filePath}: ${error.message}`);
         }
     }
+    // A legacy command directory that also held the user's files was cleaned
+    // file by file above; record what was left in it.
+    for (const dirPath of partlyCleanedDirs) {
+        try {
+            await settleLegacyCommandDir(projectPath, dirPath, result);
+        }
+        catch (error) {
+            result.errors.push(`Failed to delete directory ${dirPath}: ${error.message}`);
+        }
+    }
     // Delete managed global slash command files (these are 100% OpenSpec-managed)
     const globalPromptMatchesByPath = new Map(getLegacyGlobalPromptMatches(detection).map((prompt) => [prompt.path, prompt]));
     for (const filePath of detection.globalSlashCommandFiles) {
@@ -461,7 +607,11 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
  */
 export function formatCleanupSummary(result) {
     const lines = [];
-    if (result.deletedFiles.length > 0 || result.deletedDirs.length > 0 || result.modifiedFiles.length > 0) {
+    const keptFiles = result.keptFiles ?? [];
+    if (result.deletedFiles.length > 0 ||
+        result.deletedDirs.length > 0 ||
+        result.modifiedFiles.length > 0 ||
+        keptFiles.length > 0) {
         lines.push('Cleaned up legacy files:');
         for (const file of result.deletedFiles) {
             const replacementLabel = result.deletedFileReplacementLabels?.[file]
@@ -474,6 +624,9 @@ export function formatCleanupSummary(result) {
         for (const dir of result.deletedDirs) {
             lines.push(`  ✓ Removed ${dir}/ (replaced by OpenSpec skills and commands)`);
         }
+        for (const entry of keptFiles) {
+            lines.push(`  • Kept ${entry} (not created by OpenSpec)`);
+        }
         for (const file of result.modifiedFiles) {
             lines.push(`  ✓ Removed OpenSpec markers from ${file}`);
         }
@@ -643,8 +796,23 @@ function legacyToolIdForDir(dir) {
     }
     return undefined;
 }
+/** The files OpenSpec wrote into a repo-local legacy slash-command directory. */
+function legacyManagedFileNamesForDir(dir) {
+    const normalizedDir = normalizePathForMatch(dir);
+    for (const pattern of Object.values(LEGACY_SLASH_COMMAND_PATHS)) {
+        if (pattern.type === 'directory' && pattern.path === normalizedDir) {
+            return pattern.managedFileNames ?? [];
+        }
+    }
+    return [];
+}
 /** The tool that owns a repo-local legacy slash-command file, if any. */
 function legacyToolIdForFile(file) {
+    // A file from a directory-based tool, reported because the directory also
+    // holds the user's own files.
+    const commandDir = legacyCommandDirForFile(file);
+    if (commandDir)
+        return commandDir.toolId;
     // Normalize to forward slashes so the glob patterns match on Windows too.
     const normalizedFile = normalizePathForMatch(file);
     for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {

package/dist/core/list.js

@@ -4,12 +4,24 @@ import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progre
 import { readFileSync } from 'fs';
 import { MarkdownParser } from './parsers/markdown-parser.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { describeNestedChange, findNestedChanges, } from '../utils/nested-change.js';
 function isMissingPathError(error) {
     return (typeof error === 'object' &&
         error !== null &&
         'code' in error &&
         error.code === 'ENOENT');
 }
+/**
+ * An entry that cannot be dated because it no longer resolves: it was removed
+ * after `readdir` listed it, or it is a symlink whose target is missing (an
+ * Emacs `.#file` lock) or that loops back on itself.
+ */
+function isUnresolvableEntryError(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return false;
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ELOOP';
+}
 async function readChangeDirectoryEntries(changesDir) {
     try {
         return await fs.readdir(changesDir, { withFileTypes: true });
@@ -30,14 +42,21 @@ async function getLastModified(dirPath) {
         const entries = await fs.readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                await walk(fullPath);
-            }
-            else {
-                const stat = await fs.stat(fullPath);
-                if (latest === null || stat.mtime > latest) {
-                    latest = stat.mtime;
+            try {
+                if (entry.isDirectory()) {
+                    await walk(fullPath);
                 }
+                else {
+                    const stat = await fs.stat(fullPath);
+                    if (latest === null || stat.mtime > latest) {
+                        latest = stat.mtime;
+                    }
+                }
+            }
+            catch (error) {
+                // Skip the one entry rather than fail the listing of every change.
+                if (!isUnresolvableEntryError(error))
+                    throw error;
             }
         }
     }
@@ -96,6 +115,11 @@ export class ListCommand {
             }
             // Collect information about each change
             const changes = [];
+            // A directory that only wraps nested change directories is still listed -
+            // hiding it would hide a real change whenever the probe is wrong - but it
+            // is listed as what it is, so the nesting stops failing silently (#1846).
+            const nestedFindings = await findNestedChanges(changesDir, changeDirs);
+            const nestedByName = new Map(nestedFindings.map((finding) => [finding.name, finding]));
             for (const changeDir of changeDirs) {
                 const progress = await getTaskProgressForChange(changesDir, changeDir, targetPath);
                 const changePath = path.join(changesDir, changeDir);
@@ -104,7 +128,8 @@ export class ListCommand {
                     name: changeDir,
                     completedTasks: progress.completed,
                     totalTasks: progress.total,
-                    lastModified
+                    lastModified,
+                    ...(nestedByName.has(changeDir) ? { nested: nestedByName.get(changeDir).nested } : {})
                 });
             }
             // Sort by preference (default: recent first)
@@ -121,9 +146,22 @@ export class ListCommand {
                     completedTasks: c.completedTasks,
                     totalTasks: c.totalTasks,
                     lastModified: c.lastModified.toISOString(),
-                    status: c.totalTasks === 0 ? 'no-tasks' : c.completedTasks === c.totalTasks ? 'complete' : 'in-progress'
+                    status: c.totalTasks === 0 ? 'no-tasks' : c.completedTasks === c.totalTasks ? 'complete' : 'in-progress',
+                    ...(c.nested ? { nested: c.nested } : {})
                 }));
-                console.log(JSON.stringify({ changes: jsonOutput, ...(root ? { root } : {}) }, null, 2));
+                // Additive: the entries keep their shape so existing consumers are
+                // unaffected, and the nesting is reported alongside them.
+                const warnings = nestedFindings.map((finding) => ({
+                    code: 'nested_change_directory',
+                    name: finding.name,
+                    nested: finding.nested,
+                    message: describeNestedChange(finding)
+                }));
+                console.log(JSON.stringify({
+                    changes: jsonOutput,
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                    ...(root ? { root } : {})
+                }, null, 2));
                 return;
             }
             // Display results
@@ -132,10 +170,16 @@ export class ListCommand {
             const nameWidth = Math.max(...changes.map(c => c.name.length));
             for (const change of changes) {
                 const paddedName = change.name.padEnd(nameWidth);
-                const status = formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
+                const status = change.nested
+                    ? 'not a change'
+                    : formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
                 const timeAgo = formatRelativeTime(change.lastModified);
                 console.log(`${padding}${paddedName}     ${status.padEnd(12)}  ${timeAgo}`);
             }
+            for (const finding of nestedFindings) {
+                console.log('');
+                console.log(`Warning: ${describeNestedChange(finding)}`);
+            }
             return;
         }
         // specs mode

package/dist/core/migration.js

@@ -5,7 +5,7 @@
  * Called by both init and update commands before profile resolution.
  */
 import { AI_TOOLS } from './config.js';
-import { getGlobalConfig, getGlobalConfigPath, saveGlobalConfig } from './global-config.js';
+import { getGlobalConfig, getGlobalConfigPath, isGlobalConfigUnreadable, saveGlobalConfig } from './global-config.js';
 import { CommandAdapterRegistry } from './command-generation/index.js';
 import { resolveCommandInvocation, resolveCommandSurfaceCapability, shouldGenerateCommandsForTool, } from './command-surface.js';
 import { WORKFLOW_TO_SKILL_DIR } from './profile-sync-drift.js';
@@ -435,6 +435,11 @@ function inferDelivery(artifacts) {
  * - If profile field already exists: no-op.
  */
 export function migrateIfNeeded(projectPath, tools) {
+    // 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;
+    }
     const config = getGlobalConfig();
     // Check raw config file for profile field presence
     const configPath = getGlobalConfigPath();

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/parsers/change-parser.d.ts

@@ -20,8 +20,19 @@ export declare class ChangeParser extends MarkdownParser {
      * `view`, `list`, `spec --json`, spec validation — untouched.
      */
     protected parseRequirements(section: Section): Requirement[];
+    /**
+     * The deltas in one spec file, read by parseDeltaSpec — the reader archive
+     * applies — so what `show` reports is what archive will do. This used to be a
+     * second reader that disagreed with it: a bullet-form REMOVED was invisible,
+     * a repeated section header was read only once, and a RENAMED line written
+     * with `*` or `+` was dropped.
+     */
     private parseSpecDeltas;
-    private parseRenames;
+    /**
+     * One Requirement per block, read by the same section parser (and the
+     * header filter above) as before, so text and scenarios are unchanged.
+     */
+    private toRequirements;
     private parseSectionsFromContent;
     private getContentUntilNextHeaderFromLines;
 }