@fission-ai/openspec 1.7.0 → 1.9.0

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

@@ -0,0 +1,13 @@
+import { type AIToolOption } from '../config.js';
+export type SkillCapableTool = AIToolOption & ({
+    skillsDir: string;
+} | {
+    globalSkillsDir: string;
+});
+export declare function toolSupportsSkills(tool: AIToolOption): tool is SkillCapableTool;
+export declare function getSkillCapableTools(): SkillCapableTool[];
+export declare function hasGlobalSkillTarget(tool: AIToolOption): boolean;
+export declare function resolveToolSkillsDir(projectRoot: string, tool: SkillCapableTool, options?: {
+    homeDir?: string;
+}): string;
+//# sourceMappingURL=skill-paths.d.ts.map

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

@@ -0,0 +1,23 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AI_TOOLS } from '../config.js';
+export function toolSupportsSkills(tool) {
+    return Boolean(tool.skillsDir || tool.globalSkillsDir);
+}
+export function getSkillCapableTools() {
+    return AI_TOOLS.filter(toolSupportsSkills);
+}
+export function hasGlobalSkillTarget(tool) {
+    return Boolean(tool.globalSkillsDir);
+}
+export function resolveToolSkillsDir(projectRoot, tool, options = {}) {
+    if (tool.globalSkillsDir) {
+        const homeDir = options.homeDir ?? process.env.USERPROFILE ?? process.env.HOME ?? os.homedir();
+        return path.join(homeDir, tool.globalSkillsDir, 'skills');
+    }
+    if (tool.skillsDir) {
+        return path.join(projectRoot, tool.skillsDir, 'skills');
+    }
+    throw new Error(`Tool '${tool.value}' does not support skill generation.`);
+}
+//# sourceMappingURL=skill-paths.js.map

package/dist/core/shared/tool-detection.js

@@ -5,28 +5,18 @@
  */
 import path from 'path';
 import * as fs from 'fs';
-import { AI_TOOLS } from '../config.js';
+import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from '../config.js';
 import { CommandAdapterRegistry, generateCommands } from '../command-generation/index.js';
 import { getCommandContents } from './skill-generation.js';
 import { getGlobalConfig } from '../global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from '../profiles.js';
+import { isSharedSkillTargetActive, readSharedSkillTarget, reconcileSharedSkillTargets, } from '../shared-skill-target.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, } from '../command-surface.js';
+import { getSkillCapableTools, resolveToolSkillsDir, toolSupportsSkills, } from './skill-paths.js';
 /**
  * Names of skill directories created by openspec init.
  */
-export const SKILL_NAMES = [
-    'openspec-explore',
-    'openspec-new-change',
-    'openspec-continue-change',
-    'openspec-apply-change',
-    'openspec-update-change',
-    'openspec-ff-change',
-    'openspec-sync-specs',
-    'openspec-archive-change',
-    'openspec-bulk-archive-change',
-    'openspec-verify-change',
-    'openspec-onboard',
-    'openspec-propose',
-];
+export const SKILL_NAMES = OPENSPEC_SKILL_NAMES;
 /**
  * IDs of command templates created by openspec init.
  */
@@ -48,21 +38,26 @@ export const COMMAND_IDS = [
  * Gets the list of tools with skillsDir configured.
  */
 export function getToolsWithSkillsDir() {
-    return AI_TOOLS.filter((t) => t.skillsDir).map((t) => t.value);
+    return getSkillCapableTools().map((tool) => tool.value);
 }
 /**
  * Checks which skill files exist for a tool.
  */
 export function getToolSkillStatus(projectRoot, toolId) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
-    if (!tool?.skillsDir) {
+    if (!tool || !toolSupportsSkills(tool)) {
+        return { configured: false, fullyConfigured: false, skillCount: 0 };
+    }
+    if (tool.skillsDir && !isSharedSkillTargetActive(projectRoot, toolId)) {
         return { configured: false, fullyConfigured: false, skillCount: 0 };
     }
-    const skillsDir = path.join(projectRoot, tool.skillsDir, 'skills');
+    const skillsDirs = [
+        resolveToolSkillsDir(projectRoot, tool),
+        ...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectRoot, root, 'skills')),
+    ];
     let skillCount = 0;
     for (const skillName of SKILL_NAMES) {
-        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
-        if (fs.existsSync(skillFile)) {
+        if (skillsDirs.some((skillsDir) => fs.existsSync(path.join(skillsDir, skillName, 'SKILL.md')))) {
             skillCount++;
         }
     }
@@ -159,9 +154,21 @@ export function areCommandFilesUpToDate(projectRoot, toolId, options) {
  */
 export function getToolStates(projectRoot) {
     const states = new Map();
-    const toolIds = AI_TOOLS.filter((t) => t.skillsDir).map((t) => t.value);
-    for (const toolId of toolIds) {
-        states.set(toolId, getToolSkillStatus(projectRoot, toolId));
+    const tools = getSkillCapableTools();
+    for (const tool of tools) {
+        const skillStatus = getToolSkillStatus(projectRoot, tool.value);
+        const markerConfigured = Boolean(tool.skillsDir) &&
+            readSharedSkillTarget(projectRoot, tool.skillsDir) === tool.value;
+        states.set(tool.value, markerConfigured
+            ? { ...skillStatus, configured: true }
+            : skillStatus);
+    }
+    const configuredTools = tools.filter((tool) => tool.skillsDir && states.get(tool.value)?.configured);
+    const activeSharedTargets = new Set(reconcileSharedSkillTargets(projectRoot, configuredTools).map((tool) => tool.value));
+    for (const tool of configuredTools) {
+        if (!activeSharedTargets.has(tool.value)) {
+            states.set(tool.value, { configured: false, fullyConfigured: false, skillCount: 0 });
+        }
     }
     return states;
 }
@@ -200,7 +207,7 @@ export function extractGeneratedByVersion(skillFilePath) {
  */
 export function getToolVersionStatus(projectRoot, toolId, currentVersion, options) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
-    if (!tool?.skillsDir) {
+    if (!tool || !toolSupportsSkills(tool)) {
         return {
             toolId,
             toolName: toolId,
@@ -209,25 +216,43 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
             needsUpdate: false,
         };
     }
-    const skillsDir = path.join(projectRoot, tool.skillsDir, 'skills');
+    const skillsDirs = [
+        resolveToolSkillsDir(projectRoot, tool),
+        ...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectRoot, root, 'skills')),
+    ];
     let generatedByVersion = null;
+    let foundSkill = false;
     // 1. Find the first skill file that exists and read its version
     for (const skillName of SKILL_NAMES) {
-        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
-        if (fs.existsSync(skillFile)) {
-            generatedByVersion = extractGeneratedByVersion(skillFile);
-            break;
+        for (const skillsDir of skillsDirs) {
+            const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
+            if (fs.existsSync(skillFile)) {
+                generatedByVersion = extractGeneratedByVersion(skillFile);
+                foundSkill = true;
+                break;
+            }
         }
+        if (foundSkill)
+            break;
     }
     const skillConfigured = getToolSkillStatus(projectRoot, toolId).configured;
     const commandConfigured = toolHasAnyConfiguredCommand(projectRoot, toolId);
-    const configured = skillConfigured || commandConfigured;
+    const markerConfigured = Boolean(tool.skillsDir) &&
+        readSharedSkillTarget(projectRoot, tool.skillsDir) === toolId;
+    const configured = skillConfigured || commandConfigured || markerConfigured;
     // 2. Commands-only installs have no skill file to read a version from, so fall
     //    back to comparing the generated command content. Deliberately skipped when
     //    skill files exist: an unreadable version there must still force a rewrite.
     if (!skillConfigured && commandConfigured && areCommandFilesUpToDate(projectRoot, toolId, options)) {
         generatedByVersion = currentVersion;
     }
+    if (!skillConfigured && !commandConfigured && markerConfigured) {
+        const delivery = getGlobalConfig().delivery ?? 'both';
+        if (!shouldGenerateSkillsForTool(toolId, delivery) &&
+            !shouldGenerateCommandsForTool(toolId, delivery)) {
+            generatedByVersion = currentVersion;
+        }
+    }
     const needsUpdate = configured && (generatedByVersion === null || generatedByVersion !== currentVersion);
     return {
         toolId,
@@ -241,13 +266,19 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
  * Gets all configured tools in the project (configured via skills or commands).
  */
 export function getConfiguredTools(projectRoot) {
-    return AI_TOOLS
+    const configured = AI_TOOLS
         .filter((t) => {
-        if (!t.skillsDir)
+        if (!toolSupportsSkills(t))
             return false;
-        return getToolSkillStatus(projectRoot, t.value).configured || toolHasAnyConfiguredCommand(projectRoot, t.value);
-    })
-        .map((t) => t.value);
+        return (getToolSkillStatus(projectRoot, t.value).configured ||
+            toolHasAnyConfiguredCommand(projectRoot, t.value) ||
+            (Boolean(t.skillsDir) &&
+                readSharedSkillTarget(projectRoot, t.skillsDir) === t.value));
+    });
+    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectRoot, configured.filter((tool) => tool.skillsDir)).map((tool) => tool.value));
+    return configured
+        .filter((tool) => tool.globalSkillsDir || activeProjectTools.has(tool.value))
+        .map((tool) => tool.value);
 }
 /**
  * Gets version status for all configured tools.

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

@@ -0,0 +1,31 @@
+import { type AIToolOption } from './config.js';
+/** Reads a valid-looking marker value without letting linked roots escape. */
+export declare function readSharedSkillTarget(projectPath: string, skillsDir: string): string | undefined;
+/**
+ * A shared skill root can only hold one rendered variant of each skill.
+ * Keep the writer recorded so later updates do not infer every tool that
+ * happens to use the same directory.
+ */
+export declare function reconcileSharedSkillTargets(projectPath: string, tools: AIToolOption[]): AIToolOption[];
+/**
+ * Returns whether a tool is the active writer for its physical skills root.
+ * 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

@@ -0,0 +1,186 @@
+import path from 'path';
+import * as fs from 'fs';
+import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from './config.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+const TARGET_MARKER = '.openspec-target';
+/** Returns the ownership-marker path for one shared skills root. */
+function markerPath(projectPath, skillsDir) {
+    return path.join(projectPath, skillsDir, 'skills', TARGET_MARKER);
+}
+/** Reads a valid-looking marker value without letting linked roots escape. */
+export function readSharedSkillTarget(projectPath, skillsDir) {
+    try {
+        const target = markerPath(projectPath, skillsDir);
+        FileSystemUtils.assertProjectArtifactPath(projectPath, target);
+        return fs.readFileSync(target, 'utf-8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a tool still has an allowlisted managed skill under an old root. */
+function hasLegacySkills(projectPath, tool) {
+    return (tool.legacySkillsDirs ?? []).some((root) => {
+        const skillsDir = path.join(projectPath, root, 'skills');
+        return OPENSPEC_SKILL_NAMES.some((skillName) => {
+            try {
+                const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
+                FileSystemUtils.assertProjectArtifactPath(projectPath, skillFile);
+                return fs.existsSync(skillFile);
+            }
+            catch {
+                return false;
+            }
+        });
+    });
+}
+/**
+ * Infers pre-marker ownership from generated invocation syntax. This preserves
+ * both existing generic `.agents` trees and Codex trees users moved manually.
+ */
+function inferSharedSkillTarget(projectPath, skillsDir) {
+    let foundGenericReference = false;
+    for (const skillName of OPENSPEC_SKILL_NAMES) {
+        const skillFile = path.join(projectPath, skillsDir, 'skills', skillName, 'SKILL.md');
+        try {
+            FileSystemUtils.assertProjectArtifactPath(projectPath, skillFile);
+            const content = fs.readFileSync(skillFile, 'utf-8');
+            if (content.includes('$openspec-'))
+                return 'codex';
+            if (content.includes('/openspec-'))
+                foundGenericReference = true;
+        }
+        catch {
+            // Missing, unreadable, or out-of-project files provide no ownership signal.
+        }
+    }
+    return foundGenericReference ? 'agents' : undefined;
+}
+/** Whether the canonical shared root already contains an OpenSpec skill. */
+function hasCurrentSkills(projectPath, skillsDir) {
+    return OPENSPEC_SKILL_NAMES.some((skillName) => {
+        const skillFile = path.join(projectPath, skillsDir, 'skills', skillName, 'SKILL.md');
+        try {
+            FileSystemUtils.assertProjectArtifactPath(projectPath, skillFile);
+            return fs.existsSync(skillFile);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * A shared skill root can only hold one rendered variant of each skill.
+ * Keep the writer recorded so later updates do not infer every tool that
+ * happens to use the same directory.
+ */
+export function reconcileSharedSkillTargets(projectPath, tools) {
+    const byRoot = new Map();
+    for (const tool of tools) {
+        if (!tool.skillsDir)
+            continue;
+        const group = byRoot.get(tool.skillsDir) ?? [];
+        group.push(tool);
+        byRoot.set(tool.skillsDir, group);
+    }
+    const reconciled = [];
+    for (const group of byRoot.values()) {
+        if (group.length === 1) {
+            reconciled.push(group[0]);
+            continue;
+        }
+        const root = group[0].skillsDir;
+        const marked = readSharedSkillTarget(projectPath, root);
+        const markedTool = group.find((tool) => tool.value === marked);
+        if (markedTool) {
+            reconciled.push(markedTool);
+            continue;
+        }
+        const inferred = inferSharedSkillTarget(projectPath, root);
+        const legacyCodex = group.find((tool) => tool.value === 'codex' && hasLegacySkills(projectPath, tool));
+        if (inferred === 'agents' && legacyCodex) {
+            // Before ownership markers existed, selecting both targets produced a
+            // generic canonical tree plus a Codex-only legacy tree. Codex now emits
+            // a dual-syntax canonical tree, so it can safely consolidate that state.
+            reconciled.push(legacyCodex);
+            continue;
+        }
+        const inferredTool = group.find((tool) => tool.value === inferred);
+        if (inferredTool) {
+            reconciled.push(inferredTool);
+            continue;
+        }
+        // An unmarked canonical tree predates Codex's move into `.agents`; keep
+        // that established agents target instead of overwriting it from `.codex`.
+        if (hasCurrentSkills(projectPath, root)) {
+            reconciled.push(group.find((tool) => tool.value === 'agents') ?? group[0]);
+            continue;
+        }
+        const legacyTool = group.find((tool) => hasLegacySkills(projectPath, tool));
+        if (legacyTool) {
+            reconciled.push(legacyTool);
+            continue;
+        }
+        // `.agents` existed as the vendor-neutral target before Codex adopted it.
+        // Unmarked trees therefore retain that established meaning.
+        reconciled.push(group.find((tool) => tool.value === 'agents') ?? group[0]);
+    }
+    return reconciled;
+}
+/**
+ * Returns whether a tool is the active writer for its physical skills root.
+ * Non-shared roots are always active.
+ */
+export function isSharedSkillTargetActive(projectPath, toolId) {
+    const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
+    if (!tool?.skillsDir)
+        return false;
+    const sharingRoot = AI_TOOLS.filter((candidate) => candidate.skillsDir === tool.skillsDir);
+    if (sharingRoot.length < 2)
+        return true;
+    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)
+        return;
+    const sharingRoot = AI_TOOLS.filter((candidate) => candidate.skillsDir === tool.skillsDir);
+    if (sharingRoot.length < 2)
+        return;
+    const target = markerPath(projectPath, tool.skillsDir);
+    FileSystemUtils.assertProjectArtifactPath(projectPath, target);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${toolId}\n`, 'utf-8');
+}
+//# sourceMappingURL=shared-skill-target.js.map

package/dist/core/specs-apply.d.ts

@@ -7,7 +7,11 @@
 export interface SpecUpdate {
     /** Capability id relative to the specs root, forward-slash separated (e.g. "web" or "platform/session-layout"). */
     id: string;
+    /** Allowed root for the delta source. */
+    sourceRoot: string;
     source: string;
+    /** Allowed root for the main-spec target. */
+    targetRoot: string;
     target: string;
     exists: boolean;
 }
@@ -30,7 +34,74 @@ export declare function buildUpdatedSpec(update: SpecUpdate, changeName: string,
         renamed: number;
     };
     warnings: string[];
+    /**
+     * Every canonical `### Requirement:` block the delta could act on is gone.
+     * This is only a *candidate* signal for retirement (#1302): the validator, not
+     * this count, decides whether `rebuilt` is actually unwritable - it recognises
+     * requirement shapes this parser sweeps into the preamble, so a spec can be
+     * blockless here and still validate. See `isRetirableSpec` in archive.ts.
+     */
+    noRequirementBlocks: boolean;
+    /**
+     * Every non-blank line of the spec this merge cannot name.
+     *
+     * Retirement deletes the whole file, so the only safe question is whether the
+     * merge can account for all of it. `extractRequirementsSection` splits a spec
+     * into five slices, and auditing a subset is how this guard kept failing: for
+     * seven rounds it looked for requirement-SHAPED text and was beaten by a new
+     * disguise each time, and when it started asking where content landed it
+     * still read only the preamble and the tail - so content simply moved into a
+     * slice nobody checked, and authored prose sitting inside a removed block's
+     * raw was deleted while the report said only "Purpose" was lost.
+     *
+     * So this accounts for the whole file: the title, the `## Purpose` section,
+     * the `## Requirements` header, and, inside each requirement block, the parts
+     * that make up a requirement - its header, its statement, and its scenarios'
+     * bullets. Every other non-blank line is reported and refuses the retirement.
+     *
+     * Fails safe in every direction: a line this cannot classify counts as
+     * unaccounted, which refuses rather than deletes.
+     */
+    unaccountedContent: string[];
 }>;
+/**
+ * Retire a capability whose last requirement a delta removed: delete its main
+ * spec and prune any directories the deletion leaves empty. Returns false when
+ * there was nothing to delete.
+ *
+ * Gated by the caller on the change's `retire_capabilities` marker, so the one
+ * archive action that removes a file from `openspec/specs/` is always something
+ * the author asked for rather than something inferred from a delta's shape. The
+ * file is recoverable from git, which the report names; applying REMOVED already
+ * deletes requirement content from a main spec, so deleting the spec once
+ * nothing is left is the same operation carried to its end rather than a new
+ * kind of act.
+ *
+ * Only the generated `spec.md` is removed - a directory holding anything else (a
+ * nested capability, a hand-kept note) is left in place.
+ *
+ * The target must resolve inside the selected specs root. A capability-directory
+ * symlink must not turn a retirement marker into authorization to delete an
+ * unrelated external file. A symlinked `spec.md` itself is safe: unlink removes
+ * the link and leaves its target alone.
+ *
+ * Directory pruning IS bounded, by REAL paths rather than string prefixes:
+ * `path.resolve` collapses `..` but does not resolve symlinks, and `readdir` and
+ * `rmdir` both follow them, so a symlinked capability directory would otherwise
+ * let the walk delete directories outside the specs root entirely.
+ */
+export declare function retireSpec(update: SpecUpdate, mainSpecsDir: string, options?: {
+    silent?: boolean;
+    displayPath?: string;
+    beforeMutate?: () => Promise<void>;
+    verifyDisplaced?: (displacedPath: string) => Promise<void>;
+    deferDelete?: boolean;
+}): Promise<{
+    retired: boolean;
+    resolvedPath?: string;
+    displacedPath?: string;
+}>;
+export declare function finalizeRetiredSpec(target: string, displacedPath: string, mainSpecsDir: string): Promise<void>;
 /**
  * Write an updated spec to disk.
  */
@@ -42,6 +113,7 @@ export declare function writeUpdatedSpec(update: SpecUpdate, rebuilt: string, co
 }, options?: {
     silent?: boolean;
     displayPath?: string;
+    beforeMutate?: () => Promise<void>;
 }): Promise<void>;
 /**
  * Build a skeleton spec for new capabilities. When the delta spec authored a