@fission-ai/openspec 1.6.0-beta.1 → 1.7.0

package/dist/core/migration.js

@@ -4,12 +4,289 @@
  * One-time migration logic for existing projects when profile system is introduced.
  * 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 { CommandAdapterRegistry } from './command-generation/index.js';
+import { resolveCommandInvocation, resolveCommandSurfaceCapability, shouldGenerateCommandsForTool, } from './command-surface.js';
 import { WORKFLOW_TO_SKILL_DIR } from './profile-sync-drift.js';
+import { COMMAND_IDS } from './shared/tool-detection.js';
 import { ALL_WORKFLOWS } from './profiles.js';
+import { getSkillReferenceTransformer, getTransformerForTool } from '../utils/command-references.js';
 import path from 'path';
 import * as fs from 'fs';
+/**
+ * Former tool roots whose OpenSpec-managed content belongs under the tool's
+ * current skillsDir. User files are never touched.
+ */
+export const LEGACY_TOOL_ROOTS = {
+    // Kimi CLI became Kimi Code and moved from .kimi to .kimi-code.
+    kimi: [{ root: '.kimi', needsConsent: false }],
+    // Windsurf was rebranded to Devin Desktop on 2026-06-02 and its config
+    // directory moved to .devin/. Devin Desktop reads .windsurf/ only as a
+    // fallback and Devin Local does not read it at all, so moving is the right
+    // default — but a pre-rebrand Windsurf build reads ONLY .windsurf/, and
+    // nothing on disk tells that user apart, so the move is offered, not taken.
+    devin: [{ root: '.windsurf', needsConsent: true }],
+};
+function classifyManagedFile(source, destination) {
+    if (isSamePath(source, destination))
+        return 'skip';
+    if (!fs.existsSync(destination))
+        return 'move';
+    try {
+        return fs.readFileSync(source, 'utf-8') === fs.readFileSync(destination, 'utf-8')
+            ? 'drop'
+            : 'keep';
+    }
+    catch {
+        return 'keep';
+    }
+}
+/**
+ * Rewrites a generated command path from the tool's current root to a legacy
+ * one, so `.devin/workflows/opsx-apply.md` locates its `.windsurf/` twin
+ * without the migration hard-coding either layout.
+ *
+ * Returns undefined for adapters whose paths are absolute (global-scoped
+ * command files) or do not start at the tool root — neither can be relocated
+ * by swapping a leading segment.
+ */
+function legacyCommandPath(commandPath, currentRoot, legacyRoot) {
+    if (path.isAbsolute(commandPath))
+        return undefined;
+    const segments = commandPath.split(/[\\/]/);
+    if (segments[0] !== currentRoot)
+        return undefined;
+    segments[0] = legacyRoot;
+    return path.join(...segments);
+}
+/**
+ * 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 function findLegacyToolMigrations(projectPath) {
+    return collectLegacyToolMigrations(projectPath, false);
+}
+/**
+ * Moves OpenSpec-managed skill directories (openspec-*) and command files
+ * (opsx-*) from a tool's legacy root to its current one. When the destination
+ * already exists the legacy copy is removed instead. Legacy directories are
+ * deleted only when left empty, so user files under the old location — a
+ * hand-written Cascade workflow next to the generated ones — are preserved.
+ *
+ * @param projectPath - Project root
+ * @param toolIds - Restrict the move to these tools; omit to move every tool
+ *        whose legacy root needs no consent
+ */
+export function migrateLegacyToolDirs(projectPath, toolIds) {
+    return collectLegacyToolMigrations(projectPath, true, toolIds);
+}
+function collectLegacyToolMigrations(projectPath, apply, toolIds) {
+    const migrations = [];
+    for (const tool of AI_TOOLS) {
+        if (!tool.skillsDir)
+            continue;
+        if (toolIds && !toolIds.includes(tool.value))
+            continue;
+        for (const legacy of LEGACY_TOOL_ROOTS[tool.value] ?? []) {
+            if (legacy.root === tool.skillsDir)
+                continue;
+            // Without an explicit tool list, only moves that need no consent run.
+            if (apply && !toolIds && legacy.needsConsent)
+                continue;
+            if (!fs.existsSync(path.join(projectPath, legacy.root)))
+                continue;
+            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply);
+            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply);
+            if (apply) {
+                removeDirIfEmpty(path.join(projectPath, legacy.root, 'skills'));
+                removeDirIfEmpty(path.join(projectPath, legacy.root, 'workflows'));
+                removeDirIfEmpty(path.join(projectPath, legacy.root));
+            }
+            // Kept-only results are retained deliberately. When every legacy file
+            // differs from its counterpart nothing is movable, and dropping the
+            // record here would leave the user with two divergent copies and no
+            // word of it.
+            if (skills.moved > 0 || commands.moved > 0 || skills.kept > 0 || commands.kept > 0) {
+                migrations.push({
+                    toolId: tool.value,
+                    from: legacy.root,
+                    to: tool.skillsDir,
+                    skillDirs: skills.moved,
+                    commandFiles: commands.moved,
+                    keptInPlace: skills.kept + commands.kept,
+                    needsConsent: legacy.needsConsent,
+                });
+            }
+        }
+    }
+    return migrations;
+}
+function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply) {
+    const legacySkillsDir = path.join(projectPath, legacyRoot, 'skills');
+    if (!fs.existsSync(legacySkillsDir))
+        return { moved: 0, kept: 0 };
+    const currentSkillsDir = path.join(projectPath, currentRoot, 'skills');
+    let moved = 0;
+    let kept = 0;
+    for (const workflowId of ALL_WORKFLOWS) {
+        const dirName = WORKFLOW_TO_SKILL_DIR[workflowId];
+        const source = path.join(legacySkillsDir, dirName);
+        const sourceSkill = path.join(source, 'SKILL.md');
+        if (!fs.existsSync(sourceSkill))
+            continue;
+        const destination = path.join(currentSkillsDir, dirName);
+        const destinationSkill = path.join(destination, 'SKILL.md');
+        const disposition = classifyManagedFile(sourceSkill, destinationSkill);
+        if (disposition === 'skip')
+            continue;
+        if (disposition === 'keep') {
+            kept++;
+            continue;
+        }
+        if (!apply) {
+            moved++;
+            continue;
+        }
+        try {
+            // Move the generated file, never the directory around it. A skill
+            // directory can also hold files the user wrote, and this destination is
+            // one OpenSpec deletes on its own — commands-only delivery and a
+            // deselected workflow both remove the whole skill directory. Carrying a
+            // user's file across would be handing it to that later removal.
+            if (disposition === 'drop') {
+                fs.rmSync(sourceSkill, { force: true });
+            }
+            else {
+                fs.mkdirSync(destination, { recursive: true });
+                fs.renameSync(sourceSkill, destinationSkill);
+            }
+            // Anything the user left beside it stays under the legacy root.
+            removeDirIfEmpty(source);
+            moved++;
+        }
+        catch {
+            // Leave the legacy directory in place if it cannot be moved
+        }
+    }
+    return { moved, kept };
+}
+function migrateCommandFiles(projectPath, tool, legacyRoot, apply) {
+    const adapter = CommandAdapterRegistry.get(tool.value);
+    if (!adapter || !tool.skillsDir)
+        return { moved: 0, kept: 0 };
+    let moved = 0;
+    let kept = 0;
+    for (const commandId of COMMAND_IDS) {
+        const currentPath = adapter.getFilePath(commandId);
+        const legacyPath = legacyCommandPath(currentPath, tool.skillsDir, legacyRoot);
+        if (!legacyPath)
+            continue;
+        const source = path.join(projectPath, legacyPath);
+        if (!fs.existsSync(source))
+            continue;
+        const destination = path.join(projectPath, currentPath);
+        const disposition = classifyManagedFile(source, destination);
+        if (disposition === 'skip')
+            continue;
+        if (disposition === 'keep') {
+            kept++;
+            continue;
+        }
+        if (!apply) {
+            moved++;
+            continue;
+        }
+        try {
+            if (disposition === 'drop') {
+                fs.rmSync(source, { force: true });
+            }
+            else {
+                fs.mkdirSync(path.dirname(destination), { recursive: true });
+                fs.renameSync(source, destination);
+            }
+            moved++;
+        }
+        catch {
+            // Leave the legacy file in place if it cannot be moved
+        }
+    }
+    return { moved, kept };
+}
+/**
+ * Summarizes what a migration moved, e.g. "6 skills and 6 commands".
+ */
+export function describeLegacyMigration(migration) {
+    const parts = [];
+    if (migration.skillDirs > 0) {
+        parts.push(`${migration.skillDirs} skill${migration.skillDirs === 1 ? '' : 's'}`);
+    }
+    if (migration.commandFiles > 0) {
+        parts.push(`${migration.commandFiles} command${migration.commandFiles === 1 ? '' : 's'}`);
+    }
+    return parts.join(' and ');
+}
+/**
+ * Names OpenSpec-managed files the move deliberately left behind, so a user
+ * who customized one knows there are now two copies to reconcile.
+ */
+export function keptInPlaceNotice(migration) {
+    if (migration.keptInPlace === 0)
+        return undefined;
+    const n = migration.keptInPlace;
+    // Deliberately does not claim the difference came from an edit: an older
+    // OpenSpec version's output differs too. Either way nothing was overwritten,
+    // and the user is the one who decides which copy to keep.
+    return (`Left ${n} file${n === 1 ? '' : 's'} in ${migration.from}/ that ` +
+        `differ${n === 1 ? 's' : ''} from the copy in ${migration.to}/. Nothing was ` +
+        `overwritten — compare the two and delete the ${migration.from}/ copy once ` +
+        `you have kept anything you customized.`);
+}
+/**
+ * Whether a migration has anything to move, as opposed to only files left in
+ * place. Callers use this to avoid offering a move of nothing.
+ */
+export function hasMovableContent(migration) {
+    return migration.skillDirs > 0 || migration.commandFiles > 0;
+}
+/**
+ * Explains why a consent-gated move is being offered, in the user's terms.
+ * Keyed by tool so the reason is specific rather than a generic "files moved".
+ */
+export function legacyMigrationNotice(migration) {
+    if (migration.toolId === 'devin') {
+        return (`Windsurf is now Devin Desktop, and its config directory moved from ` +
+            `${migration.from}/ to ${migration.to}/. Devin Desktop reads ${migration.from}/ ` +
+            `only as a fallback, and Devin Local does not read it at all.`);
+    }
+    return `${migration.from}/ is the former location for this tool; ${migration.to}/ is current.`;
+}
+/**
+ * Whether two paths are the same file on disk once symlinks are resolved.
+ *
+ * Symlinking one tool root at the other is a realistic way to straddle a
+ * rebrand (`ln -s .devin .windsurf` to keep an older build working). Without
+ * this check the "destination already exists, drop the legacy copy" branch
+ * deletes the destination itself, taking the only copy with it.
+ */
+function isSamePath(a, b) {
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+function removeDirIfEmpty(dirPath) {
+    try {
+        if (fs.readdirSync(dirPath).length === 0) {
+            fs.rmdirSync(dirPath);
+        }
+    }
+    catch {
+        // Missing or non-empty directory — nothing to do
+    }
+}
 function scanInstalledWorkflowArtifacts(projectPath, tools) {
     const installed = new Set();
     let hasSkills = false;
@@ -103,6 +380,22 @@ export function migrateIfNeeded(projectPath, tools) {
     }
     saveGlobalConfig(config);
     console.log(`Migrated: custom profile with ${installedWorkflows.length} workflows`);
-    console.log("New in this version: /opsx:propose. Try 'openspec config profile core' for the streamlined experience.");
+    // Each detected tool resolves to a propose reference for its surface: the
+    // command name its generated files answer to when commands will exist for it
+    // under the effective delivery (/opsx:propose when namespaced under opsx/,
+    // /opsx-propose when the filename is the command), its documented skill
+    // invocation otherwise. When the tools disagree — including command tools
+    // mixed with skill-only tools — stay syntax-neutral rather than advertise a
+    // form that is wrong for one of them.
+    const effectiveDelivery = config.delivery ?? 'both';
+    const proposeReferences = new Set(tools.map((tool) => {
+        if (shouldGenerateCommandsForTool(tool.value, effectiveDelivery)) {
+            const transformer = getTransformerForTool(tool.value, effectiveDelivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+            return transformer ? transformer('/opsx:propose') : '/opsx:propose';
+        }
+        return getSkillReferenceTransformer(tool.value)('/opsx:propose');
+    }));
+    const proposeReference = proposeReferences.size === 1 ? [...proposeReferences][0] : 'the openspec-propose skill';
+    console.log(`New in this version: ${proposeReference}. Try 'openspec config profile core' for the streamlined experience.`);
 }
 //# sourceMappingURL=migration.js.map

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

@@ -0,0 +1,30 @@
+/**
+ * Onboarding command hints.
+ *
+ * The commands shown to a user after setup must be limited to the workflows
+ * their profile actually installs, otherwise we advertise slash commands that
+ * were correctly never generated.
+ *
+ * This module decides WHICH hints to show. How each one is spelled for a given
+ * 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';
+export type OnboardingCommand = {
+    workflow: WorkflowId;
+    command: string;
+    description: string;
+};
+/**
+ * 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
+ * longer line wraps, and the animation's cursor-up count assumes unwrapped
+ * lines. See src/ui/welcome-screen.ts.
+ */
+export declare const DESCRIPTION_BUDGET = 17;
+/**
+ * Returns the onboarding hints for the installed workflows, in lifecycle order.
+ * Returns an empty array when none of the onboarding workflows are installed.
+ */
+export declare function getOnboardingCommands(workflows: readonly string[]): OnboardingCommand[];
+//# sourceMappingURL=onboarding-commands.d.ts.map

package/dist/core/onboarding-commands.js

@@ -0,0 +1,38 @@
+/**
+ * Onboarding command hints.
+ *
+ * The commands shown to a user after setup must be limited to the workflows
+ * their profile actually installs, otherwise we advertise slash commands that
+ * were correctly never generated.
+ *
+ * This module decides WHICH hints to show. How each one is spelled for a given
+ * tool — command, skill, or a tool-specific skill prefix — is decided by
+ * src/utils/command-references.ts at the call site.
+ */
+/**
+ * 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
+ * longer line wraps, and the animation's cursor-up count assumes unwrapped
+ * lines. See src/ui/welcome-screen.ts.
+ */
+export const DESCRIPTION_BUDGET = 17;
+/**
+ * Ordered onboarding hints. Each entry is shown only when its workflow is
+ * installed, so the list follows the change lifecycle: start, then build,
+ * then implement.
+ */
+const ONBOARDING_COMMANDS = [
+    { workflow: 'propose', command: '/opsx:propose', description: 'Start a change' },
+    { workflow: 'new', command: '/opsx:new', description: 'Scaffold a change' },
+    { workflow: 'continue', command: '/opsx:continue', description: 'Next artifact' },
+    { workflow: 'apply', command: '/opsx:apply', description: 'Implement tasks' },
+];
+/**
+ * Returns the onboarding hints for the installed workflows, in lifecycle order.
+ * Returns an empty array when none of the onboarding workflows are installed.
+ */
+export function getOnboardingCommands(workflows) {
+    const installed = new Set(workflows);
+    return ONBOARDING_COMMANDS.filter((entry) => installed.has(entry.workflow));
+}
+//# sourceMappingURL=onboarding-commands.js.map

package/dist/core/parsers/change-parser.d.ts

@@ -1,10 +1,25 @@
-import { MarkdownParser } from './markdown-parser.js';
-import { Change } from '../schemas/index.js';
+import { MarkdownParser, Section } from './markdown-parser.js';
+import { Change, Requirement } from '../schemas/index.js';
 export declare class ChangeParser extends MarkdownParser {
     private changeDir;
     constructor(content: string, changeDir: string);
     parseChangeWithDeltas(name: string): Promise<Change>;
     private parseDeltaSpecs;
+    /**
+     * Read requirements from a delta section, ignoring headers that are not
+     * `### Requirement: <name>`.
+     *
+     * A delta section often carries divider headers such as
+     * `### Documentation Requirements`. The base parser treats every child header
+     * as a requirement, which invented a scenario-less requirement that does not
+     * exist (#498): archive warned about a missing scenario, and `show --json`
+     * reported an extra delta. The delta reader already skips these headers and
+     * notes them, so this keeps the two readers in agreement.
+     *
+     * Overriding here rather than in MarkdownParser keeps main spec parsing —
+     * `view`, `list`, `spec --json`, spec validation — untouched.
+     */
+    protected parseRequirements(section: Section): Requirement[];
     private parseSpecDeltas;
     private parseRenames;
     private parseSectionsFromContent;

package/dist/core/parsers/change-parser.js

@@ -2,6 +2,7 @@ import { MarkdownParser } from './markdown-parser.js';
 import { buildCodeFenceMask } from './requirement-text.js';
 import path from 'path';
 import { promises as fs } from 'fs';
+import { discoverSpecFiles } from '../../utils/spec-discovery.js';
 export class ChangeParser extends MarkdownParser {
     changeDir;
     constructor(content, changeDir) {
@@ -38,30 +39,42 @@ export class ChangeParser extends MarkdownParser {
     }
     async parseDeltaSpecs(specsDir) {
         const deltas = [];
-        try {
-            const specDirs = await fs.readdir(specsDir, { withFileTypes: true });
-            for (const dir of specDirs) {
-                if (!dir.isDirectory())
-                    continue;
-                const specName = dir.name;
-                const specFile = path.join(specsDir, specName, 'spec.md');
-                try {
-                    const content = await fs.readFile(specFile, 'utf-8');
-                    const specDeltas = this.parseSpecDeltas(specName, content);
-                    deltas.push(...specDeltas);
-                }
-                catch (error) {
-                    // Spec file might not exist, which is okay
-                    continue;
-                }
+        // Discover delta specs recursively so nested layouts like
+        // specs/<area>/<capability>/spec.md are parsed too (#1353)
+        const specFiles = await discoverSpecFiles(specsDir);
+        for (const { id, specFile } of specFiles) {
+            try {
+                const content = await fs.readFile(specFile, 'utf-8');
+                const specDeltas = this.parseSpecDeltas(id, content);
+                deltas.push(...specDeltas);
+            }
+            catch (error) {
+                // Spec file might not be readable, which is okay
+                continue;
             }
-        }
-        catch (error) {
-            // Specs directory might not exist, which is okay
-            return [];
         }
         return deltas;
     }
+    /**
+     * Read requirements from a delta section, ignoring headers that are not
+     * `### Requirement: <name>`.
+     *
+     * A delta section often carries divider headers such as
+     * `### Documentation Requirements`. The base parser treats every child header
+     * as a requirement, which invented a scenario-less requirement that does not
+     * exist (#498): archive warned about a missing scenario, and `show --json`
+     * reported an extra delta. The delta reader already skips these headers and
+     * notes them, so this keeps the two readers in agreement.
+     *
+     * Overriding here rather than in MarkdownParser keeps main spec parsing —
+     * `view`, `list`, `spec --json`, spec validation — untouched.
+     */
+    parseRequirements(section) {
+        return super.parseRequirements({
+            ...section,
+            children: section.children.filter((child) => /^Requirement:\s*\S/i.test(child.title.trim())),
+        });
+    }
     parseSpecDeltas(specName, content) {
         const deltas = [];
         const sections = this.parseSectionsFromContent(content);

package/dist/core/parsers/code-fence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared fenced-code-block detection for the Markdown parsers.
+ *
+ * Several parsers need to ignore Markdown structure (headers, requirement
+ * blocks, scenarios, delta sections) that appears inside fenced code blocks.
+ * Keeping this logic in one place avoids the drift that previously left
+ * `requirement-blocks.ts` treating fenced `### Requirement:` lines as real
+ * requirements during validation and archiving.
+ */
+/**
+ * Builds a per-line mask where `true` marks a line that is part of a fenced
+ * code block (including the opening and closing fence lines themselves).
+ */
+export declare function buildCodeFenceMask(lines: string[]): boolean[];
+//# sourceMappingURL=code-fence.d.ts.map

package/dist/core/parsers/code-fence.js

@@ -0,0 +1,49 @@
+/**
+ * Shared fenced-code-block detection for the Markdown parsers.
+ *
+ * Several parsers need to ignore Markdown structure (headers, requirement
+ * blocks, scenarios, delta sections) that appears inside fenced code blocks.
+ * Keeping this logic in one place avoids the drift that previously left
+ * `requirement-blocks.ts` treating fenced `### Requirement:` lines as real
+ * requirements during validation and archiving.
+ */
+function getFenceMarker(line) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (!fenceMatch) {
+        return null;
+    }
+    return {
+        marker: fenceMatch[1][0],
+        length: fenceMatch[1].length,
+    };
+}
+function isClosingFence(line, activeFence) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
+    return Boolean(fenceMatch &&
+        fenceMatch[1][0] === activeFence.marker &&
+        fenceMatch[1].length >= activeFence.length);
+}
+/**
+ * Builds a per-line mask where `true` marks a line that is part of a fenced
+ * code block (including the opening and closing fence lines themselves).
+ */
+export function buildCodeFenceMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let activeFence = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (!activeFence) {
+            const fence = getFenceMarker(lines[i]);
+            if (fence) {
+                activeFence = fence;
+                mask[i] = true;
+            }
+            continue;
+        }
+        mask[i] = true;
+        if (isClosingFence(lines[i], activeFence)) {
+            activeFence = null;
+        }
+    }
+    return mask;
+}
+//# sourceMappingURL=code-fence.js.map

package/dist/core/parsers/markdown-parser.js

@@ -10,7 +10,8 @@ export class MarkdownParser {
         this.currentLine = 0;
     }
     static normalizeContent(content) {
-        return content.replace(/\r\n?/g, '\n');
+        // Strip a UTF-8 BOM so a header on the first line still matches.
+        return content.replace(/^/, '').replace(/\r\n?/g, '\n');
     }
     parseSpec(name) {
         const sections = this.parseSections();

package/dist/core/parsers/requirement-blocks.d.ts

@@ -11,6 +11,14 @@ export interface RequirementsSectionParts {
     after: string;
 }
 export declare function normalizeRequirementName(name: string): string;
+/**
+ * Case- and whitespace-insensitive fold of a requirement name. Requirement
+ * matching itself is case-sensitive (normalizeRequirementName); this fold
+ * exists only for typo detection - near-miss REMOVED headers and the
+ * RENAMED+REMOVED cross-section conflict - where two spellings that differ
+ * only in case or interior whitespace mean a mistake, never two requirements.
+ */
+export declare function foldRequirementName(name: string): string;
 /**
  * Extracts the Requirements section from a spec file and parses requirement blocks.
  */