@fission-ai/openspec 1.8.0 → 1.9.0

package/dist/core/archive.js

@@ -10,7 +10,7 @@ import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, toRootO
 import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, retireSpec, finalizeRetiredSpec, } from './specs-apply.js';
 import { discoverSpecFiles, hasAnyFileUnder } from '../utils/spec-discovery.js';
 import { METADATA_FILENAME, readRetireCapabilitiesMarker, readSkipSpecsMarker } from '../utils/change-metadata.js';
-import { isNonInteractivePromptError } from '../utils/interactive.js';
+import { confirmPrompt, isNonInteractivePromptError } from '../utils/interactive.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { folderStyleNameProblem } from './id.js';
 function isMissingPathError(error) {
@@ -202,9 +202,8 @@ function rerunCommand(root, changeName, options) {
  * `User force closed the prompt` (#1479).
  */
 async function confirmOrBlock(prompt, blocked) {
-    const { confirm } = await import('@inquirer/prompts');
     try {
-        return await confirm(prompt);
+        return await confirmPrompt(prompt);
     }
     catch (error) {
         if (isNonInteractivePromptError(error)) {
@@ -1603,6 +1602,14 @@ export class ArchiveCommand {
             console.log('No active changes found.');
             return null;
         }
+        // A picker needs a real terminal, and @inquirer's `select` writes ANSI
+        // cursor escapes to stdout even when it is redirected — the same #1526
+        // mechanism the confirm prompts were fixed for. When either stream is not a
+        // TTY, refuse up front with the guidance the caught ExitPromptError would
+        // give, rather than render an escape-spewing menu into a pipe or file.
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            throw new ArchiveBlockedError('archive_change_name_required', 'A change name is required: no terminal is available to choose one from a list.', withStoreFlag(root, `openspec archive <change-name> ${rerunFlags(options).join(' ')}`));
+        }
         // Build choices with progress inline to avoid duplicate lists
         let choices = changeDirs.map(name => ({ name, value: name }));
         try {

package/dist/core/artifact-graph/resolver.d.ts

@@ -23,18 +23,6 @@ export declare function getUserSchemasDir(): string;
  * @returns The path to the project's schemas directory
  */
 export declare function getProjectSchemasDir(projectRoot: string): string;
-/**
- * Determines whether a directory entry represents a schema directory candidate.
- *
- * Returns true for real directories and for symlinks whose target is a
- * directory. `fs.Dirent.isDirectory()` reports the raw entry type, so a symlink
- * (even one pointing at a directory) has `isDirectory() === false`; we
- * dereference such entries via `fs.statSync` to admit symlinked schema dirs
- * while still rejecting symlinks-to-files and broken/dangling symlinks.
- *
- * @param parentDir - The directory containing the entry
- * @param entry - The directory entry from `fs.readdirSync(..., { withFileTypes: true })`
- */
 export declare function isSchemaDir(parentDir: string, entry: fs.Dirent): boolean;
 /**
  * Resolves a schema name to its directory path.

package/dist/core/artifact-graph/resolver.js

@@ -52,7 +52,21 @@ export function getProjectSchemasDir(projectRoot) {
  * @param parentDir - The directory containing the entry
  * @param entry - The directory entry from `fs.readdirSync(..., { withFileTypes: true })`
  */
+/**
+ * Directories `schema fork` creates transiently while swapping a fork into
+ * place: a staging copy (`.fork-staging-<rand>`, created via mkdtemp) and a
+ * backup of the previous destination (`<name>.fork-backup-<pid>-<ts>`). Either
+ * can briefly coexist with real schemas in the schemas dir, so discovery must
+ * never surface them. Real schema names are kebab-case (no dots), so excluding
+ * these dot-bearing temp names can never hide a legitimate schema.
+ */
+function isOwnedForkTempDir(name) {
+    return name.startsWith('.fork-staging-') || name.includes('.fork-backup-');
+}
 export function isSchemaDir(parentDir, entry) {
+    if (isOwnedForkTempDir(entry.name)) {
+        return false;
+    }
     if (entry.isDirectory()) {
         return true;
     }

package/dist/core/command-generation/adapters/command-code.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Command Code Command Adapter
+ *
+ * Command Code reads custom slash commands from `.commandcode/commands/`. The
+ * command name is the markdown filename without its `.md` extension, so
+ * `opsx-<id>.md` registers `/opsx-<id>` — the same flat naming Cursor and
+ * OpenCode use. See https://commandcode.ai/docs/reference/slash-commands.
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * Command Code adapter for command generation.
+ * File path: .commandcode/commands/opsx-<id>.md
+ * Format: plain Markdown with $ARGUMENTS injected after the input contract
+ *
+ * Command Code executes the full trimmed file body and substitutes invocation
+ * arguments only where the body includes one of its argument placeholders.
+ */
+export declare const commandCodeAdapter: ToolCommandAdapter;
+//# sourceMappingURL=command-code.d.ts.map

package/dist/core/command-generation/adapters/command-code.js

@@ -0,0 +1,34 @@
+/**
+ * Command Code Command Adapter
+ *
+ * Command Code reads custom slash commands from `.commandcode/commands/`. The
+ * command name is the markdown filename without its `.md` extension, so
+ * `opsx-<id>.md` registers `/opsx-<id>` — the same flat naming Cursor and
+ * OpenCode use. See https://commandcode.ai/docs/reference/slash-commands.
+ */
+import path from 'path';
+const COMMAND_CODE_INPUT_HEADING = /^\*\*Input\*\*:[^\n]*$/m;
+function injectCommandCodeArgs(body) {
+    if (/^\*\*Provided arguments\*\*:\s*(?:\$(?:ARGUMENTS|@)|\$\{(?:ARGUMENTS|@)\})\s*$/m.test(body)) {
+        return body;
+    }
+    return body.replace(COMMAND_CODE_INPUT_HEADING, (heading) => `${heading}\n**Provided arguments**: $ARGUMENTS`);
+}
+/**
+ * Command Code adapter for command generation.
+ * File path: .commandcode/commands/opsx-<id>.md
+ * Format: plain Markdown with $ARGUMENTS injected after the input contract
+ *
+ * Command Code executes the full trimmed file body and substitutes invocation
+ * arguments only where the body includes one of its argument placeholders.
+ */
+export const commandCodeAdapter = {
+    toolId: 'command-code',
+    getFilePath(commandId) {
+        return path.join('.commandcode', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `${injectCommandCodeArgs(content.body)}\n`;
+    },
+};
+//# sourceMappingURL=command-code.js.map

package/dist/core/command-generation/adapters/index.d.ts

@@ -9,6 +9,7 @@ export { auggieAdapter } from './auggie.js';
 export { bobAdapter } from './bob.js';
 export { claudeAdapter } from './claude.js';
 export { clineAdapter } from './cline.js';
+export { commandCodeAdapter } from './command-code.js';
 export { codebuddyAdapter } from './codebuddy.js';
 export { continueAdapter } from './continue.js';
 export { costrictAdapter } from './costrict.js';

package/dist/core/command-generation/adapters/index.js

@@ -9,6 +9,7 @@ export { auggieAdapter } from './auggie.js';
 export { bobAdapter } from './bob.js';
 export { claudeAdapter } from './claude.js';
 export { clineAdapter } from './cline.js';
+export { commandCodeAdapter } from './command-code.js';
 export { codebuddyAdapter } from './codebuddy.js';
 export { continueAdapter } from './continue.js';
 export { costrictAdapter } from './costrict.js';

package/dist/core/command-generation/registry.js

@@ -10,6 +10,7 @@ import { auggieAdapter } from './adapters/auggie.js';
 import { bobAdapter } from './adapters/bob.js';
 import { claudeAdapter } from './adapters/claude.js';
 import { clineAdapter } from './adapters/cline.js';
+import { commandCodeAdapter } from './adapters/command-code.js';
 import { devinAdapter } from './adapters/devin.js';
 import { codebuddyAdapter } from './adapters/codebuddy.js';
 import { continueAdapter } from './adapters/continue.js';
@@ -45,6 +46,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(bobAdapter);
         CommandAdapterRegistry.register(claudeAdapter);
         CommandAdapterRegistry.register(clineAdapter);
+        CommandAdapterRegistry.register(commandCodeAdapter);
         CommandAdapterRegistry.register(devinAdapter);
         CommandAdapterRegistry.register(codebuddyAdapter);
         CommandAdapterRegistry.register(continueAdapter);

package/dist/core/completions/command-registry.js

@@ -97,6 +97,10 @@ export const COMMAND_REGISTRY = [
                 name: 'specs',
                 description: 'Validate all specs',
             },
+            {
+                name: 'archived',
+                description: 'Validate that archived changes have all tasks completed (for pre-commit linting)',
+            },
             COMMON_FLAGS.type,
             COMMON_FLAGS.strict,
             COMMON_FLAGS.jsonValidation,
@@ -226,6 +230,7 @@ export const COMMAND_REGISTRY = [
         description: 'List available workflow schemas with descriptions',
         flags: [
             COMMON_FLAGS.json,
+            COMMON_FLAGS.store,
         ],
     },
     {

package/dist/core/config.d.ts

@@ -17,6 +17,7 @@ export interface AIToolOption {
     globalSkillsDir?: string;
     detectionPaths?: string[];
     setupNote?: string;
+    requiresIdeRestart?: boolean;
 }
 export declare const AI_TOOLS: AIToolOption[];
 /**

package/dist/core/config.js

@@ -18,41 +18,42 @@ export const OPENSPEC_MARKERS = {
     end: '<!-- OPENSPEC:END -->'
 };
 export const AI_TOOLS = [
-    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
+    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq', requiresIdeRestart: true },
+    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent', requiresIdeRestart: true },
     { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
     { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
     { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
-    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
+    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline', requiresIdeRestart: true },
+    { name: 'Command Code', value: 'command-code', available: true, successLabel: 'Command Code', skillsDir: '.commandcode' },
     { name: 'CodeArts', value: 'codeartsagent', available: true, successLabel: 'CodeArts', skillsDir: '.codeartsdoer' },
     { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.agents', legacySkillsDirs: ['.codex'], detectionPaths: ['.agents/skills', '.codex/skills'] },
-    { name: 'Devin Desktop (formerly Windsurf)', value: 'devin', available: true, successLabel: 'Devin Desktop', skillsDir: '.devin', detectionPaths: ['.devin', '.windsurf'] },
+    { name: 'Devin Desktop (formerly Windsurf)', value: 'devin', available: true, successLabel: 'Devin Desktop', skillsDir: '.devin', detectionPaths: ['.devin', '.windsurf'], requiresIdeRestart: true },
     { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
     { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
-    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
-    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
+    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue', requiresIdeRestart: true },
+    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec', requiresIdeRestart: true },
     { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
-    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
+    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor', requiresIdeRestart: true },
     { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
     { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
-    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'] },
+    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'], requiresIdeRestart: true },
     { name: 'Hermes Agent', value: 'hermes', available: true, successLabel: 'Hermes Agent', skillsDir: '.hermes', detectionPaths: ['.hermes', 'HERMES.md', '.hermes.md'], setupNote: "Hermes only loads skills from ~/.hermes/skills by default. Add this project's .hermes/skills directory to skills.external_dirs in ~/.hermes/config.yaml so Hermes picks up the generated OpenSpec skills." },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
-    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
-    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie', requiresIdeRestart: true },
+    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode', requiresIdeRestart: true },
     { name: 'Kimi Code', value: 'kimi', available: true, successLabel: 'Kimi Code', skillsDir: '.kimi-code', detectionPaths: ['.kimi-code', '.kimi'] },
-    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
-    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
+    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro', requiresIdeRestart: true },
+    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma', requiresIdeRestart: true },
     { name: 'MiniMax Code', value: 'minimax-code', available: true, successLabel: 'MiniMax Code', globalSkillsDir: '.minimax' },
     { name: 'Mistral Vibe', value: 'vibe', available: true, successLabel: 'Mistral Vibe', skillsDir: '.vibe' },
     { name: 'Oh My Pi', value: 'oh-my-pi', available: true, successLabel: 'Oh My Pi', skillsDir: '.omp' },
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
     { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
-    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
+    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder', requiresIdeRestart: true },
     { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
     { name: 'Rovo Dev CLI', value: 'rovodev', available: true, successLabel: 'Rovo Dev CLI', skillsDir: '.rovodev', detectionPaths: ['.rovodev/skills', '.rovodev'] },
-    { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo' },
-    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae' },
+    { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo', requiresIdeRestart: true },
+    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae', requiresIdeRestart: true },
     { name: 'ZCode', value: 'zcode', available: true, successLabel: 'ZCode', skillsDir: '.zcode' },
     // Vendor-neutral target for assistants that read the shared `.agents` root.
     // Detection keys off `.agents/skills` rather than the bare root: frameworks use

package/dist/core/init.js

@@ -544,6 +544,7 @@ export class InitCommand {
                 skillsRoot: isGlobalSkillTarget ? skillsPath : projectPath,
                 isGlobalSkillTarget,
                 wasConfigured: preState?.configured ?? false,
+                requiresIdeRestart: tool.requiresIdeRestart,
             });
         }
         return validatedTools;
@@ -930,14 +931,25 @@ export class InitCommand {
         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 if any tools were configured and got a surface
-        // (when nothing was generated there is nothing a restart would pick up);
-        // only mention commands when commands were actually generated. Not "slash
-        // commands": Amazon Q's generated files are prompt-library entries invoked
-        // with @, so a restart line promising slash commands would be wrong for it.
-        if ((results.createdTools.length > 0 || results.refreshedTools.length > 0) && (commandsGenerated || skillsGenerated)) {
+        // 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) {
             console.log();
-            console.log(chalk.white(commandsGenerated
+            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.'));
         }

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

@@ -206,6 +206,16 @@ export declare function getLegacyWorkflowIdsForTool(detection: LegacyDetectionRe
  * callers can safely perform the immediate, non-deferred cleanup pass.
  */
 export declare function omitGlobalLegacyPromptFiles(detection: LegacyDetectionResult): LegacyDetectionResult;
+/**
+ * Returns a detection snapshot with the repo-local slash-command artifacts of
+ * the given tools removed. The legacy-upgrade path uses this to skip cleaning a
+ * tool's legacy files when its replacement was deliberately NOT written — e.g. a
+ * Codex upgrade suppressed because the shared `.agents` root is already owned by
+ * another tool. Deleting the legacy prompt without writing its replacement would
+ * violate the cleanup contract ("remove X because replacement Y now exists") and
+ * strip the tool's only OpenSpec integration.
+ */
+export declare function omitToolLegacyArtifacts(detection: LegacyDetectionResult, toolIds: readonly string[]): LegacyDetectionResult;
 /**
  * Builds a detection snapshot containing only the selected global Codex prompt
  * matches for replacement-gated cleanup.

package/dist/core/legacy-cleanup.js

@@ -614,41 +614,42 @@ export function formatDeferredGlobalPromptSummary(detection) {
  */
 export function getToolsFromLegacyArtifacts(detection) {
     const tools = new Set();
-    // Match directories to tool IDs
     for (const dir of detection.slashCommandDirs) {
-        for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
-            if (pattern.type === 'directory' && pattern.path === dir) {
-                tools.add(toolId);
-                break;
-            }
-        }
+        const toolId = legacyToolIdForDir(dir);
+        if (toolId)
+            tools.add(toolId);
     }
-    // Match files to tool IDs using glob patterns
     for (const file of detection.slashCommandFiles) {
-        // Normalize file path to use forward slashes for consistent matching (Windows compatibility)
-        const normalizedFile = normalizePathForMatch(file);
-        for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
-            if (pattern.type === 'files' && pattern.pattern) {
-                const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
-                let matched = false;
-                for (const p of patterns) {
-                    const regex = globToRegex(p);
-                    if (regex.test(normalizedFile)) {
-                        tools.add(toolId);
-                        matched = true;
-                        break;
-                    }
-                }
-                if (matched)
-                    break;
-            }
-        }
+        const toolId = legacyToolIdForFile(file);
+        if (toolId)
+            tools.add(toolId);
     }
     for (const prompt of getLegacyGlobalPromptMatches(detection)) {
         tools.add(prompt.toolId);
     }
     return Array.from(tools);
 }
+/** The tool that owns a repo-local legacy slash-command directory, if any. */
+function legacyToolIdForDir(dir) {
+    for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
+        if (pattern.type === 'directory' && pattern.path === dir)
+            return toolId;
+    }
+    return undefined;
+}
+/** The tool that owns a repo-local legacy slash-command file, if any. */
+function legacyToolIdForFile(file) {
+    // 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)) {
+        if (pattern.type !== 'files' || !pattern.pattern)
+            continue;
+        const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
+        if (patterns.some((p) => globToRegex(p).test(normalizedFile)))
+            return toolId;
+    }
+    return undefined;
+}
 /**
  * Normalizes global Codex prompt matches so callers can rely on workflow-aware
  * metadata even when older detection results only carry file paths.
@@ -699,6 +700,27 @@ export function omitGlobalLegacyPromptFiles(detection) {
     nextDetection.hasLegacyArtifacts = hasLegacyArtifacts(nextDetection);
     return nextDetection;
 }
+/**
+ * Returns a detection snapshot with the repo-local slash-command artifacts of
+ * the given tools removed. The legacy-upgrade path uses this to skip cleaning a
+ * tool's legacy files when its replacement was deliberately NOT written — e.g. a
+ * Codex upgrade suppressed because the shared `.agents` root is already owned by
+ * another tool. Deleting the legacy prompt without writing its replacement would
+ * violate the cleanup contract ("remove X because replacement Y now exists") and
+ * strip the tool's only OpenSpec integration.
+ */
+export function omitToolLegacyArtifacts(detection, toolIds) {
+    if (toolIds.length === 0)
+        return detection;
+    const skip = new Set(toolIds);
+    const nextDetection = {
+        ...detection,
+        slashCommandDirs: detection.slashCommandDirs.filter((dir) => !skip.has(legacyToolIdForDir(dir) ?? '')),
+        slashCommandFiles: detection.slashCommandFiles.filter((file) => !skip.has(legacyToolIdForFile(file) ?? '')),
+    };
+    nextDetection.hasLegacyArtifacts = hasLegacyArtifacts(nextDetection);
+    return nextDetection;
+}
 /**
  * Builds a detection snapshot containing only the selected global Codex prompt
  * matches for replacement-gated cleanup.

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

@@ -1,4 +1,4 @@
-import { buildCodeFenceMask } from './requirement-text.js';
+import { buildCodeFenceMask, SCENARIO_HEADER } from './requirement-text.js';
 export function normalizeRequirementName(name) {
     return name.trim();
 }
@@ -289,25 +289,57 @@ export function findMissingCurrentScenarios(current, incoming) {
     }
     return missing;
 }
+/**
+ * Any non-fenced level-4 header on the given (masked) line. Reuses the spec
+ * path's SCENARIO_HEADER so the two counters cannot drift apart.
+ */
+function scenarioHeaderAt(lines, mask, index) {
+    return !mask[index] && SCENARIO_HEADER.test(lines[index]);
+}
+/**
+ * The scenario name for a `#### ` header, matching the label the author reads:
+ * the header text with the leading `####`, an optional CommonMark closing `#`
+ * run (`#### Foo ####` renders as `Foo`), and an optional `Scenario:` prefix
+ * stripped. Both the current and incoming blocks run through here, so the
+ * comparison in findMissingCurrentScenarios stays internally consistent
+ * regardless of label — and two headers that render to the same title (one
+ * ATX-closed, one not) are not mistaken for a dropped scenario.
+ */
+function scenarioNameAt(line) {
+    return line
+        .replace(SCENARIO_HEADER, '')
+        // Optional ATX closing sequence. CommonMark only treats a trailing `#` run
+        // as a close when it is preceded by a space or tab — not any Unicode space —
+        // so this uses `[ \t]`, not `\s`. A looser `\s` could strip a `#` run after
+        // an exotic space (e.g. NBSP) that CommonMark keeps, folding two distinct
+        // scenario names into one and masking a real loss. `[ \t]` keeps the fold
+        // faithful to how the header actually renders.
+        .replace(/[ \t]+#+[ \t]*$/, '')
+        .replace(/^Scenario:\s*/i, '')
+        .trim();
+}
 function parseScenarioBlocks(requirementRaw) {
     const lines = requirementRaw.replace(/\r\n?/g, '\n').split('\n');
-    // A `#### Scenario:` inside a fenced example is not a real scenario. The
-    // validator's countScenarios already ignores fenced lines; the drift check
-    // must agree with it, or a fenced sample can false-abort an archive (or
-    // mask a genuinely dropped scenario).
+    // A scenario is ANY non-fenced `#### ` header, matching the spec path's
+    // SCENARIO_HEADER / countScenarios (requirement-text.ts) exactly — not only
+    // `#### Scenario:`. The two MUST agree: a level-4 child whose header is not
+    // literally `Scenario:` (e.g. `#### Edge case`) is still a scenario the spec
+    // path counts, so a MODIFIED block that drops it would otherwise slip past
+    // this loss check and be deleted by archive with no error (the parity the
+    // SCENARIO_HEADER comment warns not to break). A `####` inside a fenced
+    // example is masked out, matching countScenarios.
     const mask = buildCodeFenceMask(lines);
     const scenarios = [];
     let index = 0;
     while (index < lines.length) {
-        const headerMatch = mask[index] ? null : lines[index].match(/^####\s*Scenario:\s*(.+)\s*$/);
-        if (!headerMatch) {
+        if (!scenarioHeaderAt(lines, mask, index)) {
             index++;
             continue;
         }
         const start = index;
-        const name = headerMatch[1].trim();
+        const name = scenarioNameAt(lines[index]);
         index++;
-        while (index < lines.length && (mask[index] || !/^####\s*Scenario:\s*(.+)\s*$/.test(lines[index]))) {
+        while (index < lines.length && !scenarioHeaderAt(lines, mask, index)) {
             index++;
         }
         scenarios.push({

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

@@ -9,6 +9,14 @@
  * `validate <change>`, `validate <spec>`, and `archive`.
  */
 export { buildCodeFenceMask } from './code-fence.js';
+/**
+ * A level-4 header. Deliberately matches ANY `####` header, not only
+ * `#### Scenario:` — the spec path treats every level-4 child of a requirement
+ * as a scenario, so the delta counter must too (parity). The delta/loss path
+ * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
+ * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
+ */
+export declare const SCENARIO_HEADER: RegExp;
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept

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

@@ -19,10 +19,11 @@ const HEADER_LINE = /^#{1,6}\s/;
 /**
  * A level-4 header. Deliberately matches ANY `####` header, not only
  * `#### Scenario:` — the spec path treats every level-4 child of a requirement
- * as a scenario, so the delta counter must too (parity). Don't tighten this to
- * `Scenario:` without changing both paths together.
+ * as a scenario, so the delta counter must too (parity). The delta/loss path
+ * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
+ * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
  */
-const SCENARIO_HEADER = /^####\s+/;
+export const SCENARIO_HEADER = /^####\s+/;
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept

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

@@ -119,7 +119,7 @@ export declare function toPlanningHome(root: ResolvedOpenSpecRoot): PlanningHome
 export declare function resolveRootForCommand(selector: StoreSelectorOptions, output?: {
     json?: boolean;
     failurePayload?: Record<string, unknown>;
-    /** Diagnostic commands inspect what exists; they never scaffold. */
+    /** Commands that require an existing root set this to false. */
     allowImplicitRoot?: boolean;
 }): Promise<ResolvedOpenSpecRoot | null>;
 //# sourceMappingURL=root-selection.d.ts.map

package/dist/core/shared-skill-target.d.ts

@@ -12,5 +12,20 @@ export declare function reconcileSharedSkillTargets(projectPath: string, tools:
  * Non-shared roots are always active.
  */
 export declare function isSharedSkillTargetActive(projectPath: string, toolId: string): boolean;
+/**
+ * The tool that already owns `toolId`'s shared skills root, when a DIFFERENT
+ * one does. Returns the owner's tool id only when the root already carries an
+ * ownership signal (a marker or generated skills) AND reconciliation resolves
+ * it to another tool. An empty or unclaimed root returns undefined, so a
+ * genuine first-time legacy upgrade — e.g. a Codex-only user with no `.agents`
+ * yet — is never reported as owned.
+ */
+export declare function sharedSkillRootOwner(projectPath: string, toolId: string): string | undefined;
+/**
+ * Whether generating `toolId` into its shared skills root would clobber a tree
+ * a DIFFERENT tool already owns — the guard the legacy-upgrade path uses before
+ * writing skills. See {@link sharedSkillRootOwner} for the ownership rules.
+ */
+export declare function sharedSkillRootOwnedByOther(projectPath: string, toolId: string): boolean;
 export declare function writeSharedSkillTarget(projectPath: string, toolId: string): void;
 //# sourceMappingURL=shared-skill-target.d.ts.map

package/dist/core/shared-skill-target.js

@@ -141,6 +141,36 @@ export function isSharedSkillTargetActive(projectPath, toolId) {
     return reconcileSharedSkillTargets(projectPath, sharingRoot)
         .some((candidate) => candidate.value === toolId);
 }
+/**
+ * The tool that already owns `toolId`'s shared skills root, when a DIFFERENT
+ * one does. Returns the owner's tool id only when the root already carries an
+ * ownership signal (a marker or generated skills) AND reconciliation resolves
+ * it to another tool. An empty or unclaimed root returns undefined, so a
+ * genuine first-time legacy upgrade — e.g. a Codex-only user with no `.agents`
+ * yet — is never reported as owned.
+ */
+export function sharedSkillRootOwner(projectPath, toolId) {
+    const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
+    if (!tool?.skillsDir)
+        return undefined;
+    const sharingRoot = AI_TOOLS.filter((candidate) => candidate.skillsDir === tool.skillsDir);
+    if (sharingRoot.length < 2)
+        return undefined;
+    const hasOwnerSignal = readSharedSkillTarget(projectPath, tool.skillsDir) !== undefined ||
+        hasCurrentSkills(projectPath, tool.skillsDir);
+    if (!hasOwnerSignal)
+        return undefined;
+    const owner = reconcileSharedSkillTargets(projectPath, sharingRoot)[0]?.value;
+    return owner && owner !== toolId ? owner : undefined;
+}
+/**
+ * Whether generating `toolId` into its shared skills root would clobber a tree
+ * a DIFFERENT tool already owns — the guard the legacy-upgrade path uses before
+ * writing skills. See {@link sharedSkillRootOwner} for the ownership rules.
+ */
+export function sharedSkillRootOwnedByOther(projectPath, toolId) {
+    return sharedSkillRootOwner(projectPath, toolId) !== undefined;
+}
 export function writeSharedSkillTarget(projectPath, toolId) {
     const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
     if (!tool?.skillsDir)

package/dist/core/specs-apply.js

@@ -404,10 +404,17 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         .concat(keptOrder.map((b) => b.raw))
         .join('\n\n')
         .trimEnd();
-    const rebuilt = [parts.before.trimEnd(), parts.headerLine, reqBody, parts.after]
-        .filter((s, idx) => !(idx === 0 && s === ''))
-        .join('\n')
-        .replace(/\n{3,}/g, '\n\n');
+    // The blank lines surrounding `## Requirements` belong to no slice: `before`
+    // and `after` carry at most one trailing/leading '\n' by construction, and
+    // the body is trimEnd()ed. Joining the slices with a bare '\n' therefore
+    // glued the heading to the Purpose paragraph and the first requirement, so
+    // every archive rewrote a well-formatted spec into that shape. Separate
+    // non-empty slices with one blank line instead.
+    const rebuilt = [parts.before.trimEnd(), parts.headerLine, reqBody, parts.after.trim()]
+        .filter((s) => s !== '')
+        .join('\n\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trimEnd() + '\n';
     return {
         rebuilt,
         counts: {