@fission-ai/openspec 1.11.0 → 1.12.0

package/README.md

@@ -172,6 +172,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
 → **[Customization](docs/customization.md)**: make it yours<br>
+→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec<br>
 → **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
 

package/dist/cli/index.js

@@ -449,6 +449,7 @@ program
     .option('--changes', 'Validate all changes')
     .option('--specs', 'Validate all specs')
     .option('--archived', 'Validate that archived changes have all tasks completed (for pre-commit linting)')
+    .option('--report <full|findings>', 'Select bulk report content: full|findings; combine with --json for JSON')
     .option('--type <type>', 'Specify item type when ambiguous: change|spec')
     .option('--strict', 'Enable strict validation mode')
     .option('--json', 'Output validation results as JSON')

package/dist/commands/change.js

@@ -480,11 +480,12 @@ export class ChangeCommand {
             }
             else {
                 console.error(`Change "${changeName}" has issues`);
-                report.issues.forEach(issue => {
-                    const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
-                    const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
-                    console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
-                });
+            }
+            report.issues.forEach(issue => {
+                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                console.error(`${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+            });
+            if (!report.valid) {
                 // Next steps footer to guide fixing issues
                 this.printNextSteps(report.issues);
                 if (!options?.json) {

package/dist/commands/validate.d.ts

@@ -1,8 +1,11 @@
+import { toRootOutput } from '../core/root-selection.js';
+type ItemType = 'change' | 'spec';
 interface ExecuteOptions {
     all?: boolean;
     changes?: boolean;
     specs?: boolean;
     archived?: boolean;
+    report?: string;
     type?: string;
     strict?: boolean;
     json?: boolean;
@@ -12,6 +15,58 @@ interface ExecuteOptions {
     store?: string;
     storePath?: string;
 }
+interface BulkItemResult {
+    id: string;
+    type: ItemType;
+    valid: boolean;
+    issues: {
+        level: 'ERROR' | 'WARNING' | 'INFO';
+        path: string;
+        message: string;
+    }[];
+    durationMs: number;
+}
+type BulkScope = 'all' | 'changes' | 'specs' | 'archived';
+interface BulkValidationResult<T extends BulkItemResult = BulkItemResult> {
+    items: T[];
+    summary: {
+        totals: {
+            items: number;
+            passed: number;
+            failed: number;
+        };
+        byType: Partial<Record<ItemType, {
+            items: number;
+            passed: number;
+            failed: number;
+        }>>;
+    };
+    root: ReturnType<typeof toRootOutput>;
+}
+/** Findings are a distinct report, not a partial full-v1 items collection. */
+export declare function projectValidationFindings<T extends BulkItemResult>(full: BulkValidationResult<T>, scope: BulkScope): {
+    report: {
+        kind: "validation-findings";
+        version: "1.0";
+        scope: BulkScope;
+        returnedItems: number;
+        totalItems: number;
+    };
+    itemFindings: T[];
+    summary: {
+        totals: {
+            items: number;
+            passed: number;
+            failed: number;
+        };
+        byType: Partial<Record<ItemType, {
+            items: number;
+            passed: number;
+            failed: number;
+        }>>;
+    };
+    root: import("../core/root-selection.js").RootOutput;
+};
 export declare class ValidateCommand {
     execute(itemName: string | undefined, options?: ExecuteOptions): Promise<void>;
     private normalizeType;
@@ -29,6 +84,8 @@ export declare class ValidateCommand {
     private validateByType;
     private printReport;
     private printNextSteps;
+    private printFindingsReport;
+    private printBulkDetails;
     private runBulkValidation;
     /**
      * Lists archived change ids from the resolved root's archive directory,

package/dist/commands/validate.js

@@ -10,9 +10,54 @@ import { nearestMatches } from '../utils/match.js';
 import { promises as fs } from 'fs';
 import { getTaskProgressDetailForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+/** Findings are a distinct report, not a partial full-v1 items collection. */
+export function projectValidationFindings(full, scope) {
+    const itemFindings = full.items.filter(item => item.issues.length > 0);
+    return {
+        report: {
+            kind: 'validation-findings',
+            version: '1.0',
+            scope,
+            returnedItems: itemFindings.length,
+            totalItems: full.summary.totals.items,
+        },
+        itemFindings,
+        summary: full.summary,
+        root: full.root,
+    };
+}
 export class ValidateCommand {
     async execute(itemName, options = {}) {
         const bulk = options.all || options.changes || options.specs;
+        let findingsScope;
+        if (options.report !== undefined) {
+            const message = options.report !== 'full' && options.report !== 'findings'
+                ? `Unknown validation report '${options.report}'.`
+                : itemName !== undefined
+                    ? 'A validation report cannot be combined with an item name.'
+                    : options.archived && bulk
+                        ? 'A validation report cannot combine archived and active scopes.'
+                        : !options.archived && !bulk
+                            ? 'A validation report requires an explicit bulk scope.'
+                            : undefined;
+            if (message) {
+                const fix = 'Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes.';
+                if (options.json) {
+                    console.log(JSON.stringify({ status: [{ severity: 'error', code: 'invalid_validation_report_request', message, fix }] }, null, 2));
+                }
+                else {
+                    console.error(`Error: ${message}`);
+                    console.error(`Fix: ${fix}`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            if (options.report === 'findings') {
+                findingsScope = options.archived ? 'archived'
+                    : options.all || (options.changes && options.specs) ? 'all'
+                        : options.changes ? 'changes' : 'specs';
+            }
+        }
         const root = await resolveRootForCommand(options, {
             json: options.json,
             ...(bulk ? { allowImplicitRoot: false } : {}),
@@ -29,6 +74,7 @@ export class ValidateCommand {
             await this.runArchivedTaskValidation(root, {
                 json: !!options.json,
                 noInteractive: resolveNoInteractive(options),
+                findingsScope,
             });
             return;
         }
@@ -37,7 +83,7 @@ export class ValidateCommand {
             await this.runBulkValidation(root, {
                 changes: !!options.all || !!options.changes,
                 specs: !!options.all || !!options.specs,
-            }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
+            }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options), findingsScope });
             return;
         }
         // No item and no flags
@@ -191,11 +237,12 @@ export class ValidateCommand {
         }
         else {
             console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
-            for (const issue of report.issues) {
-                const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
-                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
-                console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
-            }
+        }
+        for (const issue of report.issues) {
+            const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+            console.error(`${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+        }
+        if (!report.valid) {
             this.printNextSteps(type, id, root, report.issues);
         }
     }
@@ -228,6 +275,34 @@ export class ValidateCommand {
         console.error('Next steps:');
         bullets.forEach(b => console.error(`  ${b}`));
     }
+    printFindingsReport(full, scope, json, root) {
+        const findings = projectValidationFindings(full, scope);
+        if (json) {
+            console.log(JSON.stringify(findings, null, 2));
+            return;
+        }
+        console.log(`Scope: ${scope} (${findings.report.totalItems} items)`);
+        if (findings.itemFindings.length === 0) {
+            console.log('No item findings.');
+        }
+        for (const item of findings.itemFindings) {
+            console.error(`${item.type}/${item.id}`);
+            for (const issue of item.issues) {
+                console.error(`  [${issue.level}] ${issue.path}: ${issue.message}`);
+            }
+        }
+        const totals = findings.summary.totals;
+        console.log(`Totals: ${totals.passed} passed, ${totals.failed} failed (${totals.items} items)`);
+        if (scope !== 'archived')
+            this.printBulkDetails(full.items, root);
+    }
+    printBulkDetails(results, root) {
+        const firstFailure = results.find((res) => !res.valid);
+        if (firstFailure) {
+            const storeFlag = isStoreSelectedRoot(root) ? ` --store ${root.storeId}` : '';
+            console.log(`Details: openspec validate ${firstFailure.id} --type ${firstFailure.type}${storeFlag}`);
+        }
+    }
     async runBulkValidation(root, scope, opts) {
         const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
         const [changeIds, specIds] = await Promise.all([
@@ -269,7 +344,10 @@ export class ValidateCommand {
                     ...(scope.specs ? { spec: { items: 0, passed: 0, failed: 0 } } : {}),
                 },
             };
-            if (opts.json) {
+            if (opts.findingsScope) {
+                this.printFindingsReport({ items: [], summary, root: toRootOutput(root) }, opts.findingsScope, opts.json, root);
+            }
+            else if (opts.json) {
                 const out = { items: [], summary, version: '1.0', root: toRootOutput(root) };
                 console.log(JSON.stringify(out, null, 2));
             }
@@ -326,7 +404,10 @@ export class ValidateCommand {
                 ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
             },
         };
-        if (opts.json) {
+        if (opts.findingsScope) {
+            this.printFindingsReport({ items: results, summary, root: toRootOutput(root) }, opts.findingsScope, opts.json, root);
+        }
+        else if (opts.json) {
             const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
             console.log(JSON.stringify(out, null, 2));
         }
@@ -336,13 +417,13 @@ export class ValidateCommand {
                     console.log(`✓ ${res.type}/${res.id}`);
                 else
                     console.error(`✗ ${res.type}/${res.id}`);
+                for (const issue of res.issues) {
+                    const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                    console.error(`  ${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+                }
             }
             console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
-            const firstFailure = results.find((res) => !res.valid);
-            if (firstFailure) {
-                const storeFlag = isStoreSelectedRoot(root) ? ` --store ${root.storeId}` : '';
-                console.log(`Details: openspec validate ${firstFailure.id} --type ${firstFailure.type}${storeFlag}`);
-            }
+            this.printBulkDetails(results, root);
         }
         process.exitCode = failed > 0 ? 1 : 0;
     }
@@ -438,6 +519,11 @@ export class ValidateCommand {
             totals: { items: results.length, passed, failed },
             byType: { change: summarizeType(results, 'change') },
         };
+        if (opts.findingsScope) {
+            this.printFindingsReport({ items: results, summary, root: toRootOutput(root) }, opts.findingsScope, opts.json, root);
+            process.exitCode = failed > 0 ? 1 : 0;
+            return;
+        }
         if (opts.json) {
             const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
             console.log(JSON.stringify(out, null, 2));

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

@@ -0,0 +1,15 @@
+/**
+ * SourceCraft Code Assistant Command Adapter
+ *
+ * Formats commands for the SourceCraft Code Assistant VS Code extension.
+ *
+ * @see https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/slash-commands
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * SourceCraft Code Assistant adapter for command generation.
+ * File path: .codeassistant/commands/opsx-<id>.md
+ * Format: YAML frontmatter with description
+ */
+export declare const codeassistantAdapter: ToolCommandAdapter;
+//# sourceMappingURL=codeassistant.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * SourceCraft Code Assistant Command Adapter
+ *
+ * Formats commands for the SourceCraft Code Assistant VS Code extension.
+ *
+ * @see https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/slash-commands
+ */
+import path from 'path';
+import { escapeYamlValue } from '../yaml.js';
+/**
+ * SourceCraft Code Assistant adapter for command generation.
+ * File path: .codeassistant/commands/opsx-<id>.md
+ * Format: YAML frontmatter with description
+ */
+export const codeassistantAdapter = {
+    toolId: 'codeassistant',
+    getFilePath(commandId) {
+        return path.join('.codeassistant', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+description: ${escapeYamlValue(content.description)}
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=codeassistant.js.map

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

@@ -26,6 +26,7 @@ export { kiroAdapter } from './kiro.js';
 export { ohMyPiAdapter } from './oh-my-pi.js';
 export { opencodeAdapter } from './opencode.js';
 export { piAdapter } from './pi.js';
+export { codeassistantAdapter } from './codeassistant.js';
 export { qoderAdapter } from './qoder.js';
 export { lingmaAdapter } from './lingma.js';
 export { qwenAdapter } from './qwen.js';

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

@@ -26,6 +26,7 @@ export { kiroAdapter } from './kiro.js';
 export { ohMyPiAdapter } from './oh-my-pi.js';
 export { opencodeAdapter } from './opencode.js';
 export { piAdapter } from './pi.js';
+export { codeassistantAdapter } from './codeassistant.js';
 export { qoderAdapter } from './qoder.js';
 export { lingmaAdapter } from './lingma.js';
 export { qwenAdapter } from './qwen.js';

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

@@ -27,6 +27,7 @@ import { kiroAdapter } from './adapters/kiro.js';
 import { ohMyPiAdapter } from './adapters/oh-my-pi.js';
 import { opencodeAdapter } from './adapters/opencode.js';
 import { piAdapter } from './adapters/pi.js';
+import { codeassistantAdapter } from './adapters/codeassistant.js';
 import { qoderAdapter } from './adapters/qoder.js';
 import { lingmaAdapter } from './adapters/lingma.js';
 import { qwenAdapter } from './adapters/qwen.js';
@@ -63,6 +64,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(ohMyPiAdapter);
         CommandAdapterRegistry.register(opencodeAdapter);
         CommandAdapterRegistry.register(piAdapter);
+        CommandAdapterRegistry.register(codeassistantAdapter);
         CommandAdapterRegistry.register(qoderAdapter);
         CommandAdapterRegistry.register(lingmaAdapter);
         CommandAdapterRegistry.register(qwenAdapter);

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

@@ -106,6 +106,12 @@ export const COMMAND_REGISTRY = [
                 name: 'archived',
                 description: 'Validate that archived changes have all tasks completed (for pre-commit linting)',
             },
+            {
+                name: 'report',
+                description: 'Select bulk report content',
+                takesValue: true,
+                values: ['full', 'findings'],
+            },
             COMMON_FLAGS.type,
             COMMON_FLAGS.strict,
             COMMON_FLAGS.jsonValidation,

package/dist/core/config.js

@@ -54,6 +54,7 @@ export const AI_TOOLS = [
     { 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: 'SourceCraft Code Assistant', value: 'codeassistant', available: true, successLabel: 'SourceCraft Code Assistant', skillsDir: '.codeassistant' },
     { 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'] },

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,7 +20,7 @@ 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';
@@ -590,7 +591,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 +600,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
     // ═══════════════════════════════════════════════════════════
@@ -1034,27 +1035,13 @@ 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 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/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/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/specs-apply.js

@@ -214,7 +214,12 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             }
         }
     }
-    catch {
+    catch (error) {
+        // An unreadable target is not a new spec. Preserve the filesystem error
+        // for callers, rather than synthesizing a baseline or a missing-target finding.
+        const code = error?.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR')
+            throw error;
         // Target spec does not exist; MODIFIED and RENAMED are not allowed for new specs
         // REMOVED will be ignored with a warning since there's nothing to remove
         if (plan.modified.length > 0 || plan.renamed.length > 0) {

package/dist/core/templates/workflows/explore.js

@@ -1,4 +1,25 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+const PLANNING_GUIDANCE = `## Planning a Change
+
+When the user is planning a change, guide them toward shared understanding with focused discovery questions. For open-ended discussion, follow the conversation without imposing an interview or a required output.
+
+Before asking a factual question, follow the context discovery below and inspect relevant OpenSpec artifacts, source, tests, docs, and configuration. Do not ask the user to repeat facts you can verify. Summarize relevant findings without reproducing private context or rules. If evidence is missing, conflicting, or inaccessible, state that limitation and ask only for the clarification needed to proceed.
+
+- **Follow dependencies** - Resolve the next blocking decision before its dependent details. For example, clarify the user's outcome and scope before choosing an API or data model. Revisit downstream assumptions when an earlier answer changes. Skip branches that do not matter to this goal.
+- **Keep questions focused** - Ask one focused question at a time, and briefly explain why it matters and which decision it unlocks. Batch questions only if the user asks for a batch; keep them small and group related decisions.
+- **Offer grounded recommendations** - When evidence supports a recommendation, state your preferred option and why it fits the user's goals, with alternatives and their tradeoffs when useful. Do not invent intent, priorities, or external constraints: ask the user when only they can answer. Avoid a fixed question format.
+- **Keep a conversational record** - Track decisions in the conversation, not in files. Separate confirmed decisions from proposed defaults and unresolved questions. Silence is not acceptance. Accepting an answer or a batch of recommendations is not permission to write. Keep file-write confirmation separate from discovery questions and follow the guardrails below.
+
+Stop asking when the user has enough clarity. Let them pause, pivot, or defer a decision; do not exhaust every branch or force a proposal.
+
+For example, after inspecting the relevant code:
+
+\`\`\`text
+The CLI already uses SQLite and has no remote service. Is sharing state
+across devices in scope? That determines whether local storage is enough.
+If this stays a single-device tool, I recommend keeping SQLite to avoid
+adding a service to operate; shared state would need a separate sync design.
+\`\`\``;
 export function getExploreSkillTemplate() {
     return {
         name: 'openspec-explore',
@@ -24,6 +45,10 @@ ${STORE_SELECTION_GUIDANCE}
 
 ---
 
+${PLANNING_GUIDANCE}
+
+---
+
 ## What You Might Do
 
 Depending on what the user brings, you might:
@@ -341,6 +366,10 @@ ${STORE_SELECTION_GUIDANCE}
 
 ---
 
+${PLANNING_GUIDANCE}
+
+---
+
 ## What You Might Do
 
 Depending on what the user brings, you might:

package/dist/core/templates/workflows/ff-change.js

@@ -55,6 +55,10 @@ ${STORE_SELECTION_GUIDANCE}
         - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
         - \`dependencies\`: Completed artifacts to read for context
       - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
+      - **Inspect the relevant project before drafting**: Read \`context\` and \`rules\` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside \`openspec/\`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed.
+        - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
+        - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
+        - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
       - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
       - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
@@ -167,6 +171,10 @@ ${STORE_SELECTION_GUIDANCE}
         - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
         - \`dependencies\`: Completed artifacts to read for context
       - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
+      - **Inspect the relevant project before drafting**: Read \`context\` and \`rules\` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside \`openspec/\`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed.
+        - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
+        - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
+        - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
       - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
       - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file

package/dist/core/templates/workflows/propose.js

@@ -90,6 +90,10 @@ ${STORE_SELECTION_GUIDANCE}
         - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
         - \`dependencies\`: Completed artifacts to read for context
       - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
+      - **Inspect the relevant project before drafting**: Read \`context\` and \`rules\` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside \`openspec/\`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed.
+        - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
+        - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
+        - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
       - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
       - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
@@ -238,6 +242,10 @@ ${STORE_SELECTION_GUIDANCE}
         - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
         - \`dependencies\`: Completed artifacts to read for context
       - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
+      - **Inspect the relevant project before drafting**: Read \`context\` and \`rules\` first, then inspect relevant implementation, nearby tests, configuration, and documentation outside \`openspec/\`. Keep inspection read-only and proportional to the change; reuse findings for later artifacts and inspect more only as needed.
+        - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
+        - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
+        - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
       - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
       - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file

package/dist/core/update.js

@@ -13,7 +13,7 @@ import { FileSystemUtils } from '../utils/file-system.js';
 import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
-import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
+import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, omitToolLegacyArtifacts, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getGlobalConfig } from './global-config.js';
@@ -327,14 +327,9 @@ export class UpdateCommand {
         }
         console.log();
         const affectedToolIds = [...new Set([...newlyConfiguredTools, ...updatedToolIds])];
-        const shouldRestartIde = affectedToolIds.some((toolId) => {
-            const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
-            return Boolean(tool?.requiresIdeRestart &&
-                (shouldGenerateCommandsForTool(toolId, delivery) ||
-                    shouldGenerateSkillsForTool(toolId, delivery)));
-        });
-        if (shouldRestartIde) {
-            console.log(chalk.dim('Restart your IDE for changes to take effect.'));
+        const restartHint = formatIdeRestart(affectedToolIds, delivery);
+        if (restartHint) {
+            console.log(chalk.dim(restartHint));
         }
         if (failedTools.length > 0) {
             throw new Error(`OpenSpec update failed for: ${failedTools.map((tool) => tool.name).join(', ')}`);

package/dist/core/validation/validator.d.ts

@@ -19,9 +19,10 @@ export declare class Validator {
      * - No duplicates within sections; no cross-section conflicts per spec
      *
      * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
-     * against the current main specs for the scenario loss archive refuses to
-     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
-     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * against the current main specs for scenario loss (#1477), and merge
+     * conflicts are reported as INFO without changing the verdict (#1112).
+     * When `options.projectRoot` is given, the schema's tracked task files are
+     * checked for ambiguous numbering (#1520). Omitting either
      * option keeps existing library and archive callers behaving as before.
      */
     validateChangeDeltaSpecs(changeDir: string, options?: {
@@ -47,6 +48,14 @@ export declare class Validator {
     private applyChangeRules;
     private enrichTopLevelError;
     private extractNameFromPath;
+    /**
+     * Dry-run archive's merge builder without writing its result. Reusing the
+     * builder preserves its already-synced delta rules instead of duplicating them.
+     * INFO leaves the verdict unchanged: a missing target can be a typo or a
+     * requirement introduced by a sibling change that has not archived yet.
+     * This does not run archive's later merged-spec validation or retirement checks.
+     */
+    private findArchiveBlockers;
     private createReport;
     isValid(report: ValidationReport): boolean;
     private extractRequirementText;

package/dist/core/validation/validator.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { SpecSchema, ChangeSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
+import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
 import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
@@ -112,9 +113,10 @@ export class Validator {
      * - No duplicates within sections; no cross-section conflicts per spec
      *
      * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
-     * against the current main specs for the scenario loss archive refuses to
-     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
-     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * against the current main specs for scenario loss (#1477), and merge
+     * conflicts are reported as INFO without changing the verdict (#1112).
+     * When `options.projectRoot` is given, the schema's tracked task files are
+     * checked for ambiguous numbering (#1520). Omitting either
      * option keeps existing library and archive callers behaving as before.
      */
     async validateChangeDeltaSpecs(changeDir, options = {}) {
@@ -330,6 +332,20 @@ export class Validator {
                     }
                 }
             }
+            // Reuse archive's merge builder to report conflicts with the main specs.
+            // Keep structural errors and scenario loss in their existing diagnostics.
+            if (options.mainSpecsDir) {
+                issues.push(...(await this.findArchiveBlockers(changeDir, options.mainSpecsDir, [
+                    ...issues.filter((issue) => issue.level === 'ERROR').map((issue) => issue.path),
+                    // Collected in the loop above but not turned into issues until
+                    // after this try block, so they are invisible to the filter. A
+                    // delta with no parsed sections has nothing for the merge to
+                    // apply, which it reports as a failure of its own - on top of the
+                    // error that actually names the mistake.
+                    ...missingHeaderSpecs,
+                    ...emptySectionSpecs.map((spec) => spec.path),
+                ])));
+            }
         }
         catch (error) {
             // A missing specs dir (or a stray `specs` file) means no deltas;
@@ -671,6 +687,61 @@ export class Validator {
         const dotIndex = fileName.lastIndexOf('.');
         return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
     }
+    /**
+     * Dry-run archive's merge builder without writing its result. Reusing the
+     * builder preserves its already-synced delta rules instead of duplicating them.
+     * INFO leaves the verdict unchanged: a missing target can be a typo or a
+     * requirement introduced by a sibling change that has not archived yet.
+     * This does not run archive's later merged-spec validation or retirement checks.
+     */
+    async findArchiveBlockers(changeDir, mainSpecsDir, alreadyReportedPaths) {
+        const alreadyReported = new Set(alreadyReportedPaths);
+        // Only ever reaches a generated skeleton's placeholder Purpose, which this
+        // dry run discards.
+        const changeName = path.basename(changeDir);
+        const issues = [];
+        let updates;
+        try {
+            updates = await findSpecUpdates(changeDir, mainSpecsDir);
+        }
+        catch (error) {
+            // An incomplete advisory check must not discard the validation report.
+            // Source discovery already ran above; archive retains its own path guards.
+            return [{
+                    level: 'INFO',
+                    path: 'specs',
+                    message: `Could not check archive merge conflicts: ${error instanceof Error ? error.message : String(error)}`,
+                }];
+        }
+        for (const update of updates) {
+            // discoverSpecFiles builds both this id and the entryPath the checks
+            // above report under, from the same walk.
+            const entryPath = FileSystemUtils.toPosixPath(`${update.id}/spec.md`);
+            // A delta those checks already rejected would be reported twice, the
+            // second time in archive's wording rather than the wording that names
+            // the actual mistake.
+            if (alreadyReported.has(entryPath))
+                continue;
+            try {
+                await buildUpdatedSpec(update, changeName, { silent: true });
+            }
+            catch (error) {
+                // Only the thrown preconditions, which carry no errno. A filesystem
+                // error says nothing about whether the delta applies, and `validate
+                // --all` reads six changes at once, so a transient EMFILE would report
+                // a collision that is not there - the same reason the scenario-loss
+                // check above reads only the codes that mean the file is unusable.
+                if (error?.code !== undefined)
+                    continue;
+                issues.push({
+                    level: 'INFO',
+                    path: entryPath,
+                    message: `Archive would refuse this delta: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+        return issues;
+    }
     createReport(issues) {
         const errors = issues.filter(i => i.level === 'ERROR').length;
         const warnings = issues.filter(i => i.level === 'WARNING').length;

package/dist/utils/command-references.js

@@ -60,15 +60,14 @@ const SKILL_INVOCATION_PREFIX = {
     codex: '$',
 };
 /**
- * Tools that have no slash-command surface at all: skills are matched
- * automatically or invoked by natural-language prompts, never by typing a
- * `/<name>` command. Rovo Dev CLI is such a tool — `/skills` only manages
- * skills, and any `/openspec-*` form would be a dead command (see
- * docs/supported-tools.md). References for these tools are spelled as prose
- * ("the openspec-propose skill") so generated content never tells the user to
- * type a command their CLI does not register.
+ * Tools with no documented slash invocation for skills: use automatic
+ * matching or natural-language prompts instead. SourceCraft Code Assistant
+ * supports separate command files, but its skills use description matching.
+ * Rovo Dev's `/skills` only manages skills (see docs/supported-tools.md).
+ * Skill references for these tools are spelled as prose ("the openspec-propose
+ * skill") so skills-only delivery does not advertise unregistered commands.
  */
-const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev']);
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev', 'codeassistant']);
 /**
  * Whether a tool references skills by natural language rather than a slash
  * command (see NATURAL_LANGUAGE_SKILL_TOOLS).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -41,8 +41,8 @@
     "node": ">=20.19.0"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.1",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
     "@vitest/ui": "^3.2.6",
     "eslint": "^10.5.0",