@fission-ai/openspec 1.11.0 → 1.13.0

package/dist/core/update.js

@@ -13,12 +13,12 @@ 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';
 import { getProfileWorkflows, ALL_WORKFLOWS, CORE_WORKFLOWS } from './profiles.js';
-import { getOnboardingCommands } from './onboarding-commands.js';
+import { formatOptionalWorkflowsNote, getOnboardingCommands } from './onboarding-commands.js';
 import { getAvailableTools } from './available-tools.js';
 import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
 import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
@@ -134,8 +134,7 @@ export class UpdateCommand {
             await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
             // Still check for new tool directories and extra workflows
             this.detectNewTools(resolvedProjectPath, configuredTools);
-            this.displayExtraWorkflowsNote(resolvedProjectPath, configuredTools, desiredWorkflows);
-            this.displayMissingCoreWorkflowsNote(profile, desiredWorkflows);
+            this.displayProfileNotes(resolvedProjectPath, configuredTools, desiredWorkflows, profile, delivery);
             this.displaySetupNotes(configuredTools);
             return;
         }
@@ -316,9 +315,8 @@ export class UpdateCommand {
         await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
         // 13. Detect new tool directories not currently configured
         this.detectNewTools(resolvedProjectPath, configuredAndNewTools);
-        // 14. Display note about extra workflows not in profile
-        this.displayExtraWorkflowsNote(resolvedProjectPath, configuredAndNewTools, desiredWorkflows);
-        this.displayMissingCoreWorkflowsNote(profile, desiredWorkflows);
+        // 14. Display the profile notes
+        this.displayProfileNotes(resolvedProjectPath, configuredAndNewTools, desiredWorkflows, profile, delivery);
         this.displaySetupNotes(configuredAndNewTools);
         // 15. List affected tools
         if (updatedTools.length > 0) {
@@ -327,14 +325,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(', ')}`);
@@ -438,6 +431,18 @@ export class UpdateCommand {
             console.log(chalk.yellow(`Detected new ${toolNoun}: ${newToolNames.join(', ')}. Run 'openspec init' to add ${pronoun}.`));
         }
     }
+    /**
+     * Prints the profile notes, in order, with one pointer at
+     * `openspec config profile` rather than three.
+     *
+     * Every note is evaluated: reading them as one short-circuited `||` chain
+     * would swallow whichever ran second.
+     */
+    displayProfileNotes(projectPath, configuredTools, desiredWorkflows, profile, delivery) {
+        const printedExtraNote = this.displayExtraWorkflowsNote(projectPath, configuredTools, desiredWorkflows ?? []);
+        const printedMissingCoreNote = this.displayMissingCoreWorkflowsNote(profile, desiredWorkflows);
+        this.displayOptionalWorkflowsNote(configuredTools, desiredWorkflows, delivery, printedExtraNote || printedMissingCoreNote);
+    }
     /**
      * Displays a note about extra workflows installed that aren't in the current profile.
      */
@@ -447,7 +452,9 @@ export class UpdateCommand {
         const extraWorkflows = installedWorkflows.filter((w) => !profileSet.has(w));
         if (extraWorkflows.length > 0) {
             console.log(chalk.dim(`Note: ${extraWorkflows.length} extra workflows not in profile (use \`openspec config profile\` to manage)`));
+            return true;
         }
+        return false;
     }
     /**
      * Point out core workflows a custom profile is missing, so releases that
@@ -456,17 +463,48 @@ export class UpdateCommand {
      */
     displayMissingCoreWorkflowsNote(profile, workflows) {
         if (profile !== 'custom' || !workflows) {
-            return;
+            return false;
         }
         const workflowSet = new Set(workflows);
         const missing = CORE_WORKFLOWS.filter((workflow) => !workflowSet.has(workflow));
         if (missing.length === 0) {
-            return;
+            return false;
         }
         const label = missing.length === 1 ? 'workflow' : 'workflows';
         const pronoun = missing.length === 1 ? 'it' : 'them';
         console.log(chalk.dim(`Note: Your custom profile is missing ${missing.length} core ${label}: ${missing.join(', ')}`));
         console.log(chalk.dim(`Run \`openspec config profile\` to add ${pronoun}, or \`openspec config profile core\` to use the core set.`));
+        return true;
+    }
+    /**
+     * Fallback pointer to the workflows the profile leaves out.
+     *
+     * `update` already points at `openspec config profile` when files drift from
+     * the profile, and when a custom profile is missing core workflows. Neither
+     * fires for the default `core` profile, so the user `update` is most likely
+     * to be helping — the one who ran it because a command they read about never
+     * appeared — learns nothing (#1076). This covers that gap.
+     *
+     * Silent when another note already pointed at the same command, and when no
+     * configured tool can receive a workflow surface under the active delivery:
+     * adding workflows would write nothing there.
+     */
+    displayOptionalWorkflowsNote(configuredTools, workflows, delivery, alreadyPointedAtProfileConfig) {
+        if (alreadyPointedAtProfileConfig || !workflows) {
+            return;
+        }
+        const anyToolHasASurface = configuredTools.some((toolId) => shouldGenerateSkillsForTool(toolId, delivery) ||
+            shouldGenerateCommandsForTool(toolId, delivery));
+        if (!anyToolHasASurface) {
+            return;
+        }
+        const note = formatOptionalWorkflowsNote(workflows);
+        if (!note) {
+            return;
+        }
+        for (const line of note) {
+            console.log(chalk.dim(line));
+        }
     }
     /**
      * Removes skill directories for workflows when delivery changed to commands-only.

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.13.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",

package/schemas/spec-driven/schema.yaml

@@ -18,7 +18,19 @@ artifacts:
       - **Impact**: Affected code, APIs, dependencies, or systems.
 
       IMPORTANT: The Capabilities section is critical. It creates the contract between
-      proposal and specs phases. Research existing specs before filling this in.
+      proposal and specs phases. Research existing specs before filling this in:
+      run `openspec list --specs` for the project's capability inventory, then
+      `openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
+      look related - that returns a capability's purpose and requirement texts
+      without pulling whole spec files into context. Append `--store "<id>"` to
+      both commands only for a registered standalone store, and keep `--type
+      spec`: a change and a spec sharing a name is otherwise an ambiguous-item
+      error. `openspec list` without `--specs` lists in-flight changes, not
+      specs - it never shows what the project already covers. Reuse an existing
+      capability's exact path instead of introducing a near-duplicate name.
+      The filtered read is only an overview. Before deciding what is already
+      covered or what should change, read each relevant spec in full, including
+      scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
       Each capability listed here will need a corresponding spec file.
 
       Every change must either declare at least one capability (new or
@@ -63,7 +75,7 @@ artifacts:
       `<capability-path>` is the spec directory relative to `specs/` (for example,
       `user-auth` or `identity/user-auth`). Preserve the full path:
       - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
-      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
+      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
 
       There must be at least one spec file unless the change's `.openspec.yaml`
       sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`