@fission-ai/openspec 1.8.0 → 1.10.0

package/dist/core/init.js

@@ -10,7 +10,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
+import { classifyOpenSpecDir, MAX_CONTEXT_SIZE, readProjectConfig, storePointerProblem, } from './project-config.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
@@ -33,6 +33,13 @@ const { version: OPENSPEC_VERSION } = require('../../package.json');
 // Constants
 // -----------------------------------------------------------------------------
 const DEFAULT_SCHEMA = 'spec-driven';
+function formatLanguageContext(language) {
+    return [
+        `Language: ${language}`,
+        `All artifacts must be written in ${language}.`,
+        'Keep OpenSpec structural headings and SHALL/MUST keywords in English.',
+    ].join('\n');
+}
 const PROGRESS_SPINNER = {
     interval: 80,
     frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓'],
@@ -56,6 +63,7 @@ const WORKFLOW_TO_SKILL_DIR = {
 // -----------------------------------------------------------------------------
 export class InitCommand {
     toolsArg;
+    language;
     force;
     interactiveOption;
     profileOverride;
@@ -63,6 +71,7 @@ export class InitCommand {
     copilotCloudOption;
     constructor(options = {}) {
         this.toolsArg = options.tools;
+        this.language = this.normalizeLanguage(options.language);
         this.force = options.force ?? false;
         this.interactiveOption = options.interactive;
         this.profileOverride = options.profile;
@@ -97,6 +106,7 @@ export class InitCommand {
                 }
             }
         }
+        await this.assertLanguageCanBeApplied(projectPath, openspecPath);
         // Check for legacy artifacts and handle cleanup
         const deferredLegacyCleanup = await this.handleLegacyCleanup(projectPath, extendMode);
         // Migrate OpenSpec-managed skills left in renamed tool directories
@@ -517,11 +527,31 @@ export class InitCommand {
     }
     validateTools(toolIds, toolStates, projectPath) {
         const validatedTools = [];
-        const reconciledToolIds = toolIds.includes('codex') && toolIds.includes('agents')
-            ? toolIds.filter((toolId) => toolId !== 'agents')
+        const sharedAgentsTargets = ['codex', 'zed', 'agents'];
+        const selectedSharedTargets = sharedAgentsTargets.filter((toolId) => toolIds.includes(toolId));
+        // A Codex-rendered tree already serves Zed. Keep it when Zed is added later
+        // so Codex users do not lose the `$openspec-*` references they require.
+        const preserveConfiguredCodex = selectedSharedTargets.includes('zed') &&
+            toolStates.get('codex')?.configured;
+        const sharedTargetCandidates = preserveConfiguredCodex
+            ? [...new Set([...selectedSharedTargets, 'codex'])]
+            : selectedSharedTargets;
+        const sharedTargetOwner = sharedTargetCandidates.includes('codex')
+            ? 'codex'
+            : selectedSharedTargets.includes('zed')
+                ? 'zed'
+                : selectedSharedTargets[0];
+        const firstSharedIndex = toolIds.findIndex((id) => sharedAgentsTargets.includes(id));
+        const reconciledToolIds = sharedTargetCandidates.length > 1
+            ? toolIds.flatMap((toolId, index) => {
+                if (!sharedAgentsTargets.includes(toolId))
+                    return [toolId];
+                return index === firstSharedIndex && sharedTargetOwner ? [sharedTargetOwner] : [];
+            })
             : toolIds;
-        if (reconciledToolIds.length !== toolIds.length) {
-            console.log(chalk.dim('Codex and agents share .agents/skills; writing one tree with Codex and generic skill references.'));
+        if (reconciledToolIds.length !== toolIds.length ||
+            reconciledToolIds.some((toolId, index) => toolId !== toolIds[index])) {
+            console.log(chalk.dim(`Codex, Zed, and agents share .agents/skills; writing one tree for ${sharedTargetOwner}.`));
         }
         for (const toolId of reconciledToolIds) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
@@ -544,6 +574,7 @@ export class InitCommand {
                 skillsRoot: isGlobalSkillTarget ? skillsPath : projectPath,
                 isGlobalSkillTarget,
                 wasConfigured: preState?.configured ?? false,
+                requiresIdeRestart: tool.requiresIdeRestart,
             });
         }
         return validatedTools;
@@ -698,6 +729,53 @@ export class InitCommand {
     // ═══════════════════════════════════════════════════════════
     // CONFIG FILE
     // ═══════════════════════════════════════════════════════════
+    normalizeLanguage(language) {
+        if (language === undefined)
+            return undefined;
+        const normalized = language.trim();
+        if (!normalized) {
+            throw new Error('The --language option requires a non-empty value.');
+        }
+        if (/\p{Cc}|\p{Bidi_Control}|[\u200B\u2028\u2029\uFEFF]/u.test(normalized)) {
+            throw new Error('The --language option must be a single line without control or invisible formatting characters.');
+        }
+        const serializedContext = `${formatLanguageContext(normalized)}\n`;
+        if (Buffer.byteLength(serializedContext, 'utf8') > MAX_CONTEXT_SIZE) {
+            throw new Error(`The --language option is too long for OpenSpec's ${MAX_CONTEXT_SIZE / 1024}KB project context limit.`);
+        }
+        return normalized;
+    }
+    languageContext() {
+        if (!this.language)
+            return undefined;
+        return formatLanguageContext(this.language);
+    }
+    async assertLanguageCanBeApplied(projectPath, openspecPath) {
+        const languageContext = this.languageContext();
+        if (!languageContext)
+            return;
+        const configPath = path.join(openspecPath, 'config.yaml');
+        const hasConfig = fs.existsSync(configPath) ||
+            fs.existsSync(path.join(openspecPath, 'config.yml'));
+        if (!hasConfig) {
+            try {
+                FileSystemUtils.assertProjectArtifactPath(projectPath, configPath);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? `: ${error.message}` : '';
+                throw new Error(`Cannot create openspec/config.yaml for --language${reason}`);
+            }
+            if (!(await FileSystemUtils.canWriteFile(configPath))) {
+                throw new Error('Cannot create openspec/config.yaml for --language: the destination is not writable.');
+            }
+            return;
+        }
+        const existingContext = readProjectConfig(projectPath)?.context;
+        if (existingContext?.includes(languageContext))
+            return;
+        throw new Error('--language does not overwrite an existing OpenSpec config. ' +
+            'Add the language instruction to its context field instead.');
+    }
     async createConfig(openspecPath, extendMode) {
         const configPath = path.join(openspecPath, 'config.yaml');
         const configYmlPath = path.join(openspecPath, 'config.yml');
@@ -707,12 +785,19 @@ export class InitCommand {
             return 'exists';
         }
         try {
-            const yamlContent = serializeConfig({ schema: DEFAULT_SCHEMA });
+            const yamlContent = serializeConfig({
+                schema: DEFAULT_SCHEMA,
+                context: this.languageContext(),
+            });
             FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), configPath);
             await FileSystemUtils.writeFile(configPath, yamlContent);
             return 'created';
         }
-        catch {
+        catch (error) {
+            if (this.language) {
+                const reason = error instanceof Error ? `: ${error.message}` : '';
+                throw new Error(`Failed to create openspec/config.yaml for --language${reason}`);
+            }
             return 'skipped';
         }
     }
@@ -930,14 +1015,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/profiles.d.ts

@@ -20,7 +20,7 @@ export type CoreWorkflowId = (typeof CORE_WORKFLOWS)[number];
  * Resolves which workflows should be active for a given profile configuration.
  *
  * - 'core' profile always returns CORE_WORKFLOWS
- * - 'custom' profile returns the provided customWorkflows, or empty array if not provided
+ * - 'custom' profile returns the provided customWorkflows and required dependencies
  */
 export declare function getProfileWorkflows(profile: Profile, customWorkflows?: string[]): readonly string[];
 //# sourceMappingURL=profiles.d.ts.map

package/dist/core/profiles.js

@@ -30,11 +30,20 @@ export const ALL_WORKFLOWS = [
  * Resolves which workflows should be active for a given profile configuration.
  *
  * - 'core' profile always returns CORE_WORKFLOWS
- * - 'custom' profile returns the provided customWorkflows, or empty array if not provided
+ * - 'custom' profile returns the provided customWorkflows and required dependencies
  */
 export function getProfileWorkflows(profile, customWorkflows) {
     if (profile === 'custom') {
-        return customWorkflows ?? [];
+        const workflows = customWorkflows ?? [];
+        const syncDependentIndex = workflows.findIndex((workflow) => workflow === 'archive' || workflow === 'bulk-archive');
+        if (syncDependentIndex !== -1 && !workflows.includes('sync')) {
+            return [
+                ...workflows.slice(0, syncDependentIndex),
+                'sync',
+                ...workflows.slice(syncDependentIndex),
+            ];
+        }
+        return workflows;
     }
     return CORE_WORKFLOWS;
 }

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: {

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

@@ -99,6 +99,7 @@ ${STORE_SELECTION_GUIDANCE}
    **Pause if:**
    - Task is unclear → ask for clarification
    - Implementation reveals a design issue → suggest updating artifacts
+   - A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
@@ -169,6 +170,8 @@ What would you like to do?
 - Keep code changes minimal and scoped to each task
 - Update task checkbox immediately after completing each task
 - Pause on errors, blockers, or unclear requirements - don't guess
+- When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
+- Only mark a task \`- [x]\` when its specified behavior is fully implemented, not when it is partially done or deferred
 - Use contextFiles from CLI output, don't assume specific file names
 - Do not use context or operation guidance as proof that a task is complete
 - Apply relevant project context; report conflicts with controlling workflow inputs

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

@@ -39,6 +39,7 @@ export function getFeedbackSkillTemplate() {
 5. **Submit on confirmation**
    - Use the \`openspec feedback\` command to submit
    - Format: \`openspec feedback "title" --body "body content"\`
+   - The command preserves the title text in the issue body and shortens long GitHub issue titles
    - The command will automatically add metadata (version, platform, timestamp)
 
 **Example Draft**

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

@@ -374,12 +374,12 @@ Here are the implementation tasks:
 
 ## 1. [Category or file]
 
-- [ ] 1.1 [Specific task]
-- [ ] 1.2 [Specific task]
+- [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]
+- [ ] 1.2 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]
 
-## 2. Verify
+## 2. Integration Verification
 
-- [ ] 2.1 [Verification step]
+- [ ] 2.1 Verify [broader integration or system behavior] with [end-to-end test or observable result]
 
 ---
 

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

@@ -42,7 +42,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Use a different schema only if the user:**
    - Explicitly requests a specific schema by name → use \`--schema <schema-name>\`
-   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; \`schemas\` does not accept \`--store\`. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
+   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; when a registered store was explicitly selected, append \`--store "<store-id>"\` to \`openspec schemas --json\` as well. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
 
    Otherwise, omit \`--schema\` to preserve the configured default.
 
@@ -190,7 +190,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Use a different schema only if the user:**
    - Explicitly requests a specific schema by name → use \`--schema <schema-name>\`
-   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; \`schemas\` does not accept \`--store\`. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
+   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; when a registered store was explicitly selected, append \`--store "<store-id>"\` to \`openspec schemas --json\` as well. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
 
    Otherwise, omit \`--schema\` to preserve the configured default.
 

package/dist/core/templates/workflows/store-selection.d.ts

@@ -4,5 +4,5 @@
  * Interpolated into every workflow's instructions so generated skills
  * consistently teach how to target a registered store with `--store <id>`.
  */
-export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change \"<name>\" --json --store \"<id>\"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
+export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change \"<name>\" --json --store \"<id>\"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
 //# sourceMappingURL=store-selection.d.ts.map

package/dist/core/templates/workflows/store-selection.js

@@ -4,5 +4,5 @@
  * Interpolated into every workflow's instructions so generated skills
  * consistently teach how to target a registered store with `--store <id>`.
  */
-export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`, \`view\`). Once selected, treat \`--store <id>\` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run \`openspec status --change "<name>" --json --store "<id>"\`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
+export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`, \`schemas\`, \`view\`). Once selected, treat \`--store <id>\` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run \`openspec status --change "<name>" --json --store "<id>"\`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
 //# sourceMappingURL=store-selection.js.map