@fission-ai/openspec 1.7.0 → 1.9.0

package/dist/core/migration.d.ts

@@ -14,6 +14,8 @@ export interface LegacyToolRoot {
      * location may still be the live one for somebody.
      */
     needsConsent: boolean;
+    /** Migrations that need a freshly generated destination run afterward. */
+    timing?: 'before-generation' | 'after-generation';
 }
 /**
  * Former tool roots whose OpenSpec-managed content belongs under the tool's
@@ -32,8 +34,8 @@ export interface LegacyToolMigration {
     commandFiles: number;
     /**
      * OpenSpec-managed files left under the legacy root because the copy there
-     * differs from the one that survives — the user edited it, so it is reported
-     * rather than dropped.
+     * differs materially from the one that survives, so it is reported rather
+     * than dropped.
      */
     keptInPlace: number;
     /** Whether this move needs the user's consent first */
@@ -43,7 +45,7 @@ export interface LegacyToolMigration {
  * Reports the OpenSpec content sitting under each tool's legacy root, without
  * moving anything. Callers use this to ask before a move that needs consent.
  */
-export declare function findLegacyToolMigrations(projectPath: string): LegacyToolMigration[];
+export declare function findLegacyToolMigrations(projectPath: string, timing?: 'before-generation' | 'after-generation'): LegacyToolMigration[];
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
  * (opsx-*) from a tool's legacy root to its current one. When the destination
@@ -55,7 +57,7 @@ export declare function findLegacyToolMigrations(projectPath: string): LegacyToo
  * @param toolIds - Restrict the move to these tools; omit to move every tool
  *        whose legacy root needs no consent
  */
-export declare function migrateLegacyToolDirs(projectPath: string, toolIds?: string[]): LegacyToolMigration[];
+export declare function migrateLegacyToolDirs(projectPath: string, toolIds?: string[], timing?: 'before-generation' | 'after-generation'): LegacyToolMigration[];
 /**
  * Summarizes what a migration moved, e.g. "6 skills and 6 commands".
  */

package/dist/core/migration.js

@@ -12,8 +12,12 @@ import { WORKFLOW_TO_SKILL_DIR } from './profile-sync-drift.js';
 import { COMMAND_IDS } from './shared/tool-detection.js';
 import { ALL_WORKFLOWS } from './profiles.js';
 import { getSkillReferenceTransformer, getTransformerForTool } from '../utils/command-references.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { isSharedSkillTargetActive } from './shared-skill-target.js';
+import { isLegacyCodexSkillEquivalentToCurrent } from './shared/skill-content-equivalence.js';
 import path from 'path';
 import * as fs from 'fs';
+import { resolveToolSkillsDir, toolSupportsSkills } from './shared/skill-paths.js';
 /**
  * Former tool roots whose OpenSpec-managed content belongs under the tool's
  * current skillsDir. User files are never touched.
@@ -27,6 +31,9 @@ export const LEGACY_TOOL_ROOTS = {
     // default — but a pre-rebrand Windsurf build reads ONLY .windsurf/, and
     // nothing on disk tells that user apart, so the move is offered, not taken.
     devin: [{ root: '.windsurf', needsConsent: true }],
+    // Codex now reads the canonical shared .agents root. Generate the current
+    // replacement first so a divergent legacy file is preserved, not overwritten.
+    codex: [{ root: '.codex', needsConsent: false, timing: 'after-generation' }],
 };
 function classifyManagedFile(source, destination) {
     if (isSamePath(source, destination))
@@ -34,7 +41,12 @@ function classifyManagedFile(source, destination) {
     if (!fs.existsSync(destination))
         return 'move';
     try {
-        return fs.readFileSync(source, 'utf-8') === fs.readFileSync(destination, 'utf-8')
+        const sourceContent = fs.readFileSync(source, 'utf-8');
+        const destinationContent = fs.readFileSync(destination, 'utf-8');
+        const equivalentGeneratedSkills = path.basename(source) === 'SKILL.md' &&
+            path.basename(destination) === 'SKILL.md' &&
+            isLegacyCodexSkillEquivalentToCurrent(sourceContent, destinationContent);
+        return sourceContent === destinationContent || equivalentGeneratedSkills
             ? 'drop'
             : 'keep';
     }
@@ -64,8 +76,8 @@ function legacyCommandPath(commandPath, currentRoot, legacyRoot) {
  * Reports the OpenSpec content sitting under each tool's legacy root, without
  * moving anything. Callers use this to ask before a move that needs consent.
  */
-export function findLegacyToolMigrations(projectPath) {
-    return collectLegacyToolMigrations(projectPath, false);
+export function findLegacyToolMigrations(projectPath, timing = 'before-generation') {
+    return collectLegacyToolMigrations(projectPath, false, undefined, timing);
 }
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
@@ -78,10 +90,10 @@ export function findLegacyToolMigrations(projectPath) {
  * @param toolIds - Restrict the move to these tools; omit to move every tool
  *        whose legacy root needs no consent
  */
-export function migrateLegacyToolDirs(projectPath, toolIds) {
-    return collectLegacyToolMigrations(projectPath, true, toolIds);
+export function migrateLegacyToolDirs(projectPath, toolIds, timing = 'before-generation') {
+    return collectLegacyToolMigrations(projectPath, true, toolIds, timing);
 }
-function collectLegacyToolMigrations(projectPath, apply, toolIds) {
+function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation') {
     const migrations = [];
     for (const tool of AI_TOOLS) {
         if (!tool.skillsDir)
@@ -89,19 +101,31 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds) {
         if (toolIds && !toolIds.includes(tool.value))
             continue;
         for (const legacy of LEGACY_TOOL_ROOTS[tool.value] ?? []) {
+            const legacyTiming = legacy.timing ?? 'before-generation';
+            if (legacyTiming !== timing)
+                continue;
             if (legacy.root === tool.skillsDir)
                 continue;
             // Without an explicit tool list, only moves that need no consent run.
             if (apply && !toolIds && legacy.needsConsent)
                 continue;
-            if (!fs.existsSync(path.join(projectPath, legacy.root)))
+            const legacyRootPath = path.join(projectPath, legacy.root);
+            if (!fs.existsSync(legacyRootPath))
+                continue;
+            try {
+                FileSystemUtils.assertProjectArtifactPath(projectPath, legacyRootPath);
+                FileSystemUtils.assertProjectArtifactPath(projectPath, path.join(projectPath, tool.skillsDir));
+            }
+            catch {
+                console.warn(`Skipping legacy ${legacy.root}/ migration because the directory resolves outside this project.`);
                 continue;
-            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply);
+            }
+            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation');
             const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply);
             if (apply) {
-                removeDirIfEmpty(path.join(projectPath, legacy.root, 'skills'));
-                removeDirIfEmpty(path.join(projectPath, legacy.root, 'workflows'));
-                removeDirIfEmpty(path.join(projectPath, legacy.root));
+                removeDirIfEmpty(path.join(legacyRootPath, 'skills'));
+                removeDirIfEmpty(path.join(legacyRootPath, 'workflows'));
+                removeDirIfEmpty(legacyRootPath);
             }
             // Kept-only results are retained deliberately. When every legacy file
             // differs from its counterpart nothing is movable, and dropping the
@@ -122,7 +146,7 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds) {
     }
     return migrations;
 }
-function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply) {
+function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false) {
     const legacySkillsDir = path.join(projectPath, legacyRoot, 'skills');
     if (!fs.existsSync(legacySkillsDir))
         return { moved: 0, kept: 0 };
@@ -137,6 +161,12 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply) {
             continue;
         const destination = path.join(currentSkillsDir, dirName);
         const destinationSkill = path.join(destination, 'SKILL.md');
+        if (requireDestination && !fs.existsSync(destinationSkill))
+            continue;
+        if (!areProjectArtifacts(projectPath, sourceSkill, destinationSkill)) {
+            console.warn(`Skipping legacy ${legacyRoot}/skills/${dirName} migration because it resolves outside this project.`);
+            continue;
+        }
         const disposition = classifyManagedFile(sourceSkill, destinationSkill);
         if (disposition === 'skip')
             continue;
@@ -186,6 +216,10 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply) {
         if (!fs.existsSync(source))
             continue;
         const destination = path.join(projectPath, currentPath);
+        if (!areProjectArtifacts(projectPath, source, destination)) {
+            console.warn(`Skipping legacy ${legacyPath} migration because it resolves outside this project.`);
+            continue;
+        }
         const disposition = classifyManagedFile(source, destination);
         if (disposition === 'skip')
             continue;
@@ -277,6 +311,17 @@ function isSamePath(a, b) {
         return false;
     }
 }
+function areProjectArtifacts(projectPath, ...artifactPaths) {
+    try {
+        for (const artifactPath of artifactPaths) {
+            FileSystemUtils.assertProjectArtifactPath(projectPath, artifactPath);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function removeDirIfEmpty(dirPath) {
     try {
         if (fs.readdirSync(dirPath).length === 0) {
@@ -287,20 +332,31 @@ function removeDirIfEmpty(dirPath) {
         // Missing or non-empty directory — nothing to do
     }
 }
-function scanInstalledWorkflowArtifacts(projectPath, tools) {
+function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills = false) {
     const installed = new Set();
     let hasSkills = false;
     let hasCommands = false;
     for (const tool of tools) {
-        if (!tool.skillsDir)
+        if (!toolSupportsSkills(tool))
             continue;
-        const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
-        for (const workflowId of ALL_WORKFLOWS) {
-            const skillDirName = WORKFLOW_TO_SKILL_DIR[workflowId];
-            const skillFile = path.join(skillsDir, skillDirName, 'SKILL.md');
-            if (fs.existsSync(skillFile)) {
-                installed.add(workflowId);
-                hasSkills = true;
+        const skillsDirs = [];
+        if (tool.globalSkillsDir) {
+            skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
+        }
+        else if (isSharedSkillTargetActive(projectPath, tool.value)) {
+            skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
+            if (includeLegacySkills) {
+                skillsDirs.push(...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectPath, root, 'skills')));
+            }
+        }
+        for (const skillsDir of skillsDirs) {
+            for (const workflowId of ALL_WORKFLOWS) {
+                const skillDirName = WORKFLOW_TO_SKILL_DIR[workflowId];
+                const skillFile = path.join(skillsDir, skillDirName, 'SKILL.md');
+                if (fs.existsSync(skillFile)) {
+                    installed.add(workflowId);
+                    hasSkills = true;
+                }
             }
         }
         const adapter = CommandAdapterRegistry.get(tool.value);
@@ -366,7 +422,7 @@ export function migrateIfNeeded(projectPath, tools) {
         return;
     }
     // Scan for installed workflows
-    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools);
+    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true);
     const installedWorkflows = artifacts.workflows;
     if (installedWorkflows.length === 0) {
         // No workflows installed, new user — defaults will apply

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

@@ -53,4 +53,14 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+/**
+ * Scenario names the current requirement block has and the incoming
+ * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
+ * so every name reported here would be dropped from the main spec.
+ *
+ * Shared by archive (which refuses to apply the block) and validate (which
+ * reports the same loss at authoring time, #1477), so the two cannot disagree
+ * about what counts as a dropped scenario.
+ */
+export declare function findMissingCurrentScenarios(current: RequirementBlock, incoming: RequirementBlock): string[];
 //# sourceMappingURL=requirement-blocks.d.ts.map

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();
 }
@@ -257,4 +257,96 @@ function parseRenamedPairs(sectionBody) {
     }
     return pairs;
 }
+/**
+ * Scenario names the current requirement block has and the incoming
+ * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
+ * so every name reported here would be dropped from the main spec.
+ *
+ * Shared by archive (which refuses to apply the block) and validate (which
+ * reports the same loss at authoring time, #1477), so the two cannot disagree
+ * about what counts as a dropped scenario.
+ */
+export function findMissingCurrentScenarios(current, incoming) {
+    // Multiplicity-aware: a name present N times in current and M times in
+    // incoming means max(0, N - M) instances are missing. Set membership would
+    // treat N>M as fully covered and let archive silently drop duplicates
+    // (residual #1246 / duplicate-scenario-name blind spot).
+    const remainingIncoming = new Map();
+    for (const scenario of parseScenarioBlocks(incoming.raw)) {
+        const name = scenario.name;
+        remainingIncoming.set(name, (remainingIncoming.get(name) ?? 0) + 1);
+    }
+    const missing = [];
+    for (const scenario of parseScenarioBlocks(current.raw)) {
+        const name = scenario.name;
+        const remaining = remainingIncoming.get(name) ?? 0;
+        if (remaining > 0) {
+            remainingIncoming.set(name, remaining - 1);
+        }
+        else {
+            missing.push(name);
+        }
+    }
+    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 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) {
+        if (!scenarioHeaderAt(lines, mask, index)) {
+            index++;
+            continue;
+        }
+        const start = index;
+        const name = scenarioNameAt(lines[index]);
+        index++;
+        while (index < lines.length && !scenarioHeaderAt(lines, mask, index)) {
+            index++;
+        }
+        scenarios.push({
+            name,
+            raw: lines.slice(start, index).join('\n').trimEnd(),
+        });
+    }
+    return scenarios;
+}
 //# sourceMappingURL=requirement-blocks.js.map

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/parsers/spec-structure.d.ts

@@ -1,5 +1,5 @@
 export interface MainSpecStructureIssue {
-    kind: 'delta-header' | 'requirement-outside-requirements';
+    kind: 'delta-header' | 'requirement-outside-requirements' | 'duplicate-requirement';
     line: number;
     header: string;
     message: string;

package/dist/core/parsers/spec-structure.js

@@ -8,6 +8,7 @@ export function findMainSpecStructureIssues(content) {
     const stripped = stripFencedCodeBlocksPreservingLines(normalized);
     const lines = stripped.split('\n');
     const issues = [];
+    const requirementLines = new Map();
     const requirementsHeaderIndex = lines.findIndex(line => REQUIREMENTS_SECTION_HEADER.test(line));
     let requirementsEndIndex = lines.length;
     if (requirementsHeaderIndex !== -1) {
@@ -30,7 +31,7 @@ export function findMainSpecStructureIssues(content) {
                 line: i + 1,
                 header: trimmed,
                 message: `Main spec contains delta header "${trimmed}". ` +
-                    'Delta headers are only valid inside openspec/changes/<name>/specs/<capability>/spec.md ' +
+                    'Delta headers are only valid inside openspec/changes/<name>/specs/<capability-path>/spec.md ' +
                     'and truncate the parsed ## Requirements section.',
             });
             continue;
@@ -50,6 +51,21 @@ export function findMainSpecStructureIssues(content) {
                 message: `Requirement header "${trimmed}" appears outside the main ## Requirements section. ` +
                     'Main specs only parse requirements inside that section, so this requirement is currently invisible to validate, list, and archive.',
             });
+            continue;
+        }
+        const requirementName = requirementMatch[1].trim();
+        const previousLine = requirementLines.get(requirementName);
+        if (previousLine !== undefined) {
+            issues.push({
+                kind: 'duplicate-requirement',
+                line: i + 1,
+                header: trimmed,
+                message: `Requirement header "${trimmed}" duplicates the requirement declared on line ${previousLine}. ` +
+                    'Requirement names must be unique so spec updates cannot discard one block while updating another.',
+            });
+        }
+        else {
+            requirementLines.set(requirementName, i + 1);
         }
     }
     return issues;

package/dist/core/profile-sync-drift.js

@@ -5,6 +5,10 @@ import { ALL_WORKFLOWS } from './profiles.js';
 import { CommandAdapterRegistry } from './command-generation/index.js';
 import { getConfiguredTools } from './shared/index.js';
 import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
+import { readSharedSkillTarget } from './shared-skill-target.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { isLegacyCodexSkillEquivalentToCurrent } from './shared/skill-content-equivalence.js';
+import { hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/skill-paths.js';
 /**
  * Maps workflow IDs to their skill directory names.
  */
@@ -41,14 +45,45 @@ export function getConfiguredToolsForProfileSync(projectPath) {
  */
 export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
-    if (!tool?.skillsDir)
+    if (!tool || !toolSupportsSkills(tool))
         return false;
     const knownDesiredWorkflows = toKnownWorkflows(desiredWorkflows);
     const desiredWorkflowSet = new Set(knownDesiredWorkflows);
-    const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+    const skillsDir = resolveToolSkillsDir(projectPath, tool);
     const adapter = CommandAdapterRegistry.get(toolId);
     const shouldGenerateSkills = shouldGenerateSkillsForTool(toolId, delivery);
     const shouldGenerateCommands = shouldGenerateCommandsForTool(toolId, delivery);
+    const sharedTarget = tool.skillsDir
+        ? readSharedSkillTarget(projectPath, tool.skillsDir)
+        : undefined;
+    for (const root of tool.legacySkillsDirs ?? []) {
+        for (const workflow of knownDesiredWorkflows) {
+            const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
+            const legacySkill = path.join(projectPath, root, 'skills', dirName, 'SKILL.md');
+            if (!fs.existsSync(legacySkill))
+                continue;
+            const currentSkill = path.join(skillsDir, dirName, 'SKILL.md');
+            if (!fs.existsSync(currentSkill) || sharedTarget !== toolId) {
+                return true;
+            }
+            try {
+                if (FileSystemUtils.canonicalizeExistingPath(legacySkill) ===
+                    FileSystemUtils.canonicalizeExistingPath(currentSkill)) {
+                    continue;
+                }
+                // Equivalent generated copies are actionable: migration can safely
+                // remove the redundant legacy file even when version, line endings,
+                // or supported invocation syntax changed. Materially divergent copies
+                // stay in place without forcing an update on every run.
+                if (isLegacyCodexSkillEquivalentToCurrent(fs.readFileSync(legacySkill, 'utf-8'), fs.readFileSync(currentSkill, 'utf-8'))) {
+                    return true;
+                }
+            }
+            catch {
+                return true;
+            }
+        }
+    }
     if (shouldGenerateSkills) {
         for (const workflow of knownDesiredWorkflows) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
@@ -68,7 +103,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
             }
         }
     }
-    else if (shouldRemoveSkillsForTool(toolId, delivery)) {
+    else if (shouldRemoveSkillsForTool(toolId, delivery) && !hasGlobalSkillTarget(tool)) {
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             const skillDir = path.join(skillsDir, dirName);
@@ -116,10 +151,10 @@ export function getToolsNeedingProfileSync(projectPath, desiredWorkflows, delive
 }
 function getInstalledWorkflowsForTool(projectPath, toolId, options) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
-    if (!tool?.skillsDir)
+    if (!tool || !toolSupportsSkills(tool))
         return [];
     const installed = new Set();
-    const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+    const skillsDir = resolveToolSkillsDir(projectPath, tool);
     if (options.includeSkills) {
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];

package/dist/core/project-config.d.ts

@@ -31,6 +31,9 @@ export declare const ProjectConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     store: z.ZodOptional<z.ZodString>;
+    githubCopilot: z.ZodOptional<z.ZodObject<{
+        cloudAgent: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Normalized in-memory shape of a referenced store declaration. */
 export interface DeclarationEntry {

package/dist/core/project-config.js

@@ -57,6 +57,15 @@ export const ProjectConfigSchema = z.object({
         .string()
         .optional()
         .describe('Store id used as the OpenSpec root when no local planning shape exists'),
+    // Optional: GitHub Copilot integration preferences. `cloudAgent` is the
+    // opt-in for generating the Copilot cloud coding-agent files (a GitHub
+    // Actions workflow + agent file); absent means "not yet decided".
+    githubCopilot: z
+        .object({
+        cloudAgent: z.boolean().optional(),
+    })
+        .optional()
+        .describe('GitHub Copilot integration preferences'),
 });
 export function loadOperationInputs(projectConfig, operationId) {
     const context = projectConfig?.context !== undefined && projectConfig.context.trim().length > 0
@@ -235,7 +244,11 @@ export function readProjectConfig(projectRoot) {
             const rulesField = z.record(z.string(), z.array(z.string()));
             // First check if it's an object structure (guard against null since typeof null === 'object')
             if (typeof raw.rules === 'object' && raw.rules !== null && !Array.isArray(raw.rules)) {
-                const parsedRules = {};
+                // Artifact ids are intentionally not restricted to the built-in naming
+                // convention, so keys such as "constructor" remain valid for custom
+                // schemas. A null-prototype map preserves those keys as data without
+                // letting "__proto__" mutate the lookup object's prototype.
+                const parsedRules = Object.create(null);
                 let hasValidRules = false;
                 for (const [artifactId, rules] of Object.entries(raw.rules)) {
                     const rulesArrayResult = z.array(z.string()).safeParse(rules);
@@ -281,6 +294,23 @@ export function readProjectConfig(projectRoot) {
                 console.warn(`Warning: ignoring invalid store: field in ${configPathForWarnings(projectRoot)} (must be a single store id string).`);
             }
         }
+        // Parse githubCopilot preferences (only cloudAgent is recognized today).
+        if (raw.githubCopilot !== undefined) {
+            if (typeof raw.githubCopilot === 'object' &&
+                raw.githubCopilot !== null &&
+                !Array.isArray(raw.githubCopilot)) {
+                const cloudAgent = raw.githubCopilot.cloudAgent;
+                if (typeof cloudAgent === 'boolean') {
+                    config.githubCopilot = { cloudAgent };
+                }
+                else if (cloudAgent !== undefined) {
+                    console.warn(`Invalid 'githubCopilot.cloudAgent' field in config (must be a boolean)`);
+                }
+            }
+            else {
+                console.warn(`Invalid 'githubCopilot' field in config (must be an object)`);
+            }
+        }
         // Return partial config even if some fields failed
         return Object.keys(config).length > 0 ? config : null;
     }

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/index.d.ts

@@ -5,4 +5,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';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/shared/index.js

@@ -5,4 +5,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';
 //# sourceMappingURL=index.js.map

package/dist/core/shared/skill-content-equivalence.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns whether a legacy Codex skill differs from the current canonical
+ * replacement only by generated version, checkout line endings/BOM, or the
+ * known Codex/generic dual-reference expansion.
+ */
+export declare function isLegacyCodexSkillEquivalentToCurrent(legacyContent: string, currentContent: string): boolean;
+//# sourceMappingURL=skill-content-equivalence.d.ts.map

package/dist/core/shared/skill-content-equivalence.js

@@ -0,0 +1,41 @@
+import { OPENSPEC_SKILL_NAMES } from '../config.js';
+const GENERATED_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const OPENSPEC_SKILL_NAME_SET = new Set(OPENSPEC_SKILL_NAMES);
+/**
+ * Normalizes checkout line endings and a valid generated version inside the
+ * YAML frontmatter. Free-form `generatedBy` text in the instructions remains
+ * material.
+ */
+function normalizeGeneratedSkill(content) {
+    const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const frontmatter = normalized.match(/^---\n[\s\S]*?\n---(?:\n|$)/)?.[0];
+    if (!frontmatter)
+        return normalized;
+    const versionLine = /^(\s*generatedBy:\s*)(?:"([^"\n]+)"|'([^'\n]+)'|([^\s"'#]+))\s*$/m;
+    const normalizedFrontmatter = frontmatter.replace(versionLine, (line, prefix, doubleQuoted, singleQuoted, bare) => {
+        const version = doubleQuoted ?? singleQuoted ?? bare;
+        return version && GENERATED_VERSION.test(version)
+            ? `${prefix}"<generated-version>"`
+            : line;
+    });
+    return normalizedFrontmatter + normalized.slice(frontmatter.length);
+}
+/**
+ * Converts only known generated dual references in current Codex content back
+ * to the direct syntax used by legacy `.codex` output.
+ */
+function toLegacyCodexReferences(content) {
+    return content.replace(/\$(openspec-[a-z0-9-]+) \(Codex\) or \/\1 \(other agents\)/g, (match, skillName) => OPENSPEC_SKILL_NAME_SET.has(skillName) ? `$${skillName}` : match);
+}
+/**
+ * Returns whether a legacy Codex skill differs from the current canonical
+ * replacement only by generated version, checkout line endings/BOM, or the
+ * known Codex/generic dual-reference expansion.
+ */
+export function isLegacyCodexSkillEquivalentToCurrent(legacyContent, currentContent) {
+    const normalizedLegacy = normalizeGeneratedSkill(legacyContent);
+    const normalizedCurrent = normalizeGeneratedSkill(currentContent);
+    return (normalizedLegacy === normalizedCurrent ||
+        normalizedLegacy === toLegacyCodexReferences(normalizedCurrent));
+}
+//# sourceMappingURL=skill-content-equivalence.js.map