@fission-ai/openspec 1.6.0 → 1.8.0

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

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+export declare const OPERATION_IDS: readonly ["apply", "archive"];
+export type OperationId = (typeof OPERATION_IDS)[number];
+export interface OperationConfig {
+    guidance?: string[];
+}
+export type OperationsConfig = Partial<Record<OperationId, OperationConfig>>;
 /**
  * Zod schema for project configuration.
  *
@@ -16,7 +22,18 @@ export declare const ProjectConfigSchema: z.ZodObject<{
     schema: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    operations: z.ZodOptional<z.ZodObject<{
+        apply: z.ZodOptional<z.ZodObject<{
+            guidance: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        archive: z.ZodOptional<z.ZodObject<{
+            guidance: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, 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 {
@@ -27,6 +44,11 @@ export interface DeclarationEntry {
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema> & {
     references?: DeclarationEntry[];
 };
+export interface OperationInputs {
+    context?: string;
+    operationGuidance?: string[];
+}
+export declare function loadOperationInputs(projectConfig: ProjectConfig | null, operationId: OperationId): OperationInputs;
 export declare const MAX_CONTEXT_SIZE: number;
 /**
  * Read and parse openspec/config.yaml from project root.
@@ -49,16 +71,16 @@ export declare const MAX_CONTEXT_SIZE: number;
  */
 export declare function readProjectConfig(projectRoot: string): ProjectConfig | null;
 /**
- * Validate artifact IDs in rules against a schema's artifacts.
- * Called during instruction loading (when schema is known).
- * Returns warnings for unknown artifact IDs.
+ * Validate artifact IDs in rules against the artifacts of every available
+ * schema. The `rules:` map is global, but each change can use a different
+ * schema, so a key is only unknown when it matches no artifact in ANY schema.
+ * Returns warnings for keys that are unknown everywhere.
  *
  * @param rules - The rules object from config
- * @param validArtifactIds - Set of valid artifact IDs from the schema
- * @param schemaName - Name of the schema for error messages
+ * @param validArtifactIds - Set of valid artifact IDs across all schemas
  * @returns Array of warning messages for unknown artifact IDs
  */
-export declare function validateConfigRules(rules: Record<string, string[]>, validArtifactIds: Set<string>, schemaName: string): string[];
+export declare function validateConfigRules(rules: Record<string, string[]>, validArtifactIds: Set<string>): string[];
 /**
  * Suggest valid schema names when user provides invalid schema.
  * Uses fuzzy matching to find similar names.

package/dist/core/project-config.js

@@ -2,6 +2,10 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
+export const OPERATION_IDS = ['apply', 'archive'];
+const OperationConfigSchema = z.object({
+    guidance: z.array(z.string()).optional(),
+});
 /**
  * Zod schema for project configuration.
  *
@@ -34,6 +38,14 @@ export const ProjectConfigSchema = z.object({
     )
         .optional()
         .describe('Per-artifact rules, keyed by artifact ID'),
+    // Optional: per-operation advisory guidance, kept separate from artifact rules.
+    operations: z
+        .object({
+        apply: OperationConfigSchema.optional(),
+        archive: OperationConfigSchema.optional(),
+    })
+        .optional()
+        .describe('Per-operation advisory guidance'),
     // Note: the `references` field (id strings or {id, remote} maps) is
     // deliberately absent here — readProjectConfig parses and normalizes
     // it by hand (see DeclarationEntry below); a schema entry nothing
@@ -45,7 +57,70 @@ 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
+        ? projectConfig.context
+        : undefined;
+    const guidance = projectConfig?.operations?.[operationId]?.guidance;
+    const operationGuidance = guidance && guidance.length > 0 ? guidance : undefined;
+    return {
+        ...(context !== undefined ? { context } : {}),
+        ...(operationGuidance !== undefined ? { operationGuidance } : {}),
+    };
+}
+function parseOperations(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        console.warn(`Invalid 'operations' field in config (must be object)`);
+        return undefined;
+    }
+    const supported = new Set(OPERATION_IDS);
+    const operations = {};
+    for (const [operationId, value] of Object.entries(raw)) {
+        if (!supported.has(operationId)) {
+            console.warn(`Unknown operation ID '${operationId}' in config. Supported operation IDs: ${OPERATION_IDS.join(', ')}`);
+            continue;
+        }
+        const typedOperationId = operationId;
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            console.warn(`Invalid 'operations.${operationId}' field in config (must be object), ignoring this operation`);
+            continue;
+        }
+        const operation = value;
+        const unknownFields = Object.keys(operation).filter((field) => field !== 'guidance');
+        if (unknownFields.length > 0) {
+            console.warn(`Unknown field(s) in 'operations.${operationId}': ${unknownFields.join(', ')}. Supported fields: guidance`);
+        }
+        if (operation.guidance === undefined) {
+            continue;
+        }
+        const guidanceResult = z.array(z.string()).safeParse(operation.guidance);
+        if (!guidanceResult.success) {
+            console.warn(`Guidance for operation '${operationId}' must be an array of strings, ignoring this operation's guidance`);
+            continue;
+        }
+        const guidance = guidanceResult.data.filter((entry) => entry.length > 0);
+        if (guidance.length < guidanceResult.data.length) {
+            console.warn(`Some guidance for operation '${operationId}' are empty strings, ignoring them`);
+        }
+        if (guidance.length > 0) {
+            operations[typedOperationId] = { guidance };
+        }
+    }
+    return Object.keys(operations).length > 0 ? operations : undefined;
+}
 /**
  * Parser for `references:` declarations: string entries or
  * {id, remote} maps, normalized to DeclarationEntry[]. Dedup keys on
@@ -169,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);
@@ -196,6 +275,10 @@ export function readProjectConfig(projectRoot) {
                 console.warn(`Invalid 'rules' field in config (must be object)`);
             }
         }
+        const operations = parseOperations(raw.operations);
+        if (operations) {
+            config.operations = operations;
+        }
         const references = parseDeclarationList(raw.references);
         if (references) {
             config.references = references;
@@ -211,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;
     }
@@ -223,22 +323,22 @@ function configPathForWarnings(projectRoot) {
     return resolveConfigFilePath(projectRoot) ?? path.join(projectRoot, 'openspec', 'config.yaml');
 }
 /**
- * Validate artifact IDs in rules against a schema's artifacts.
- * Called during instruction loading (when schema is known).
- * Returns warnings for unknown artifact IDs.
+ * Validate artifact IDs in rules against the artifacts of every available
+ * schema. The `rules:` map is global, but each change can use a different
+ * schema, so a key is only unknown when it matches no artifact in ANY schema.
+ * Returns warnings for keys that are unknown everywhere.
  *
  * @param rules - The rules object from config
- * @param validArtifactIds - Set of valid artifact IDs from the schema
- * @param schemaName - Name of the schema for error messages
+ * @param validArtifactIds - Set of valid artifact IDs across all schemas
  * @returns Array of warning messages for unknown artifact IDs
  */
-export function validateConfigRules(rules, validArtifactIds, schemaName) {
+export function validateConfigRules(rules, validArtifactIds) {
     const warnings = [];
     for (const artifactId of Object.keys(rules)) {
         if (!validArtifactIds.has(artifactId)) {
             const validIds = Array.from(validArtifactIds).sort().join(', ');
             warnings.push(`Unknown artifact ID in rules: "${artifactId}". ` +
-                `Valid IDs for schema "${schemaName}": ${validIds}`);
+                `It matches no artifact in any available schema. Known artifact IDs: ${validIds}`);
         }
     }
     return warnings;

package/dist/core/references.js

@@ -53,6 +53,46 @@ function registerFix(id, remote) {
     }
     return `Get a checkout from a teammate and run: openspec store register <path> --id ${id}`;
 }
+const WHITESPACE = /\s/;
+/**
+ * Drop a CommonMark closing sequence (`## Purpose ##`). The closing run only
+ * counts when whitespace precedes it, so `Purpose###` keeps its hashes.
+ * Scans from the end so the cost stays linear in the title length.
+ */
+function stripClosingSequence(title) {
+    let end = title.length;
+    while (end > 0 && WHITESPACE.test(title[end - 1])) {
+        end--;
+    }
+    const hashEnd = end;
+    while (end > 0 && title[end - 1] === '#') {
+        end--;
+    }
+    const noClosingRun = end === hashEnd;
+    const missingLeadingSpace = end === 0 || !WHITESPACE.test(title[end - 1]);
+    if (noClosingRun || missingLeadingSpace) {
+        return title.trim();
+    }
+    return title.slice(0, end).trim();
+}
+/**
+ * Heading title, or null when the line is not an ATX heading. Hand-rolled
+ * rather than a regex so a title padded with whitespace cannot backtrack.
+ */
+function parseHeadingTitle(line) {
+    let level = 0;
+    while (level < 6 && level < line.length && line[level] === '#') {
+        level++;
+    }
+    if (level === 0 || level >= line.length || !WHITESPACE.test(line[level])) {
+        return null;
+    }
+    let start = level;
+    while (start < line.length && WHITESPACE.test(line[start])) {
+        start++;
+    }
+    return stripClosingSequence(line.slice(start));
+}
 /**
  * Tolerant first-Purpose-line extraction. parseSpec() throws on specs
  * without Purpose/Requirements sections; the index must never fail on an
@@ -79,12 +119,11 @@ export function extractFirstPurposeLine(markdown) {
         if (fenceMarker !== null) {
             continue;
         }
-        const heading = line.match(/^(#{1,6})\s+(.*)$/);
-        if (heading) {
+        const title = parseHeadingTitle(line);
+        if (title !== null) {
             if (inPurpose) {
                 return '';
             }
-            const title = heading[2].replace(/\s+#+\s*$/, '').trim();
             inPurpose = title.toLowerCase() === 'purpose';
             continue;
         }
@@ -152,7 +191,6 @@ export function renderReferencedStoresSection(entries) {
  * let hostile content forge instruction lines (slice 6.1 hardening).
  */
 export function sanitizeInline(value, maxLength = 300) {
-    // eslint-disable-next-line no-control-regex
     const flattened = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
     return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
 }

package/dist/core/relationship-health.d.ts

@@ -26,6 +26,10 @@ export interface RelationshipHealth {
             remote?: string;
         };
         origin_url?: string;
+        drift?: {
+            ahead: number;
+            behind: number;
+        };
         status: StoreDiagnostic[];
     } | null;
     references: ReferenceIndexEntry[];
@@ -42,6 +46,10 @@ export interface InspectRelationshipsInput {
         metadataValid: boolean;
         canonicalRemote?: string;
         originUrl?: string;
+        drift?: {
+            ahead: number;
+            behind: number;
+        };
     };
     referenceEntries: ReferenceIndexEntry[];
     registryUnreadable: boolean;

package/dist/core/relationship-health.js

@@ -37,6 +37,18 @@ export function inspectRelationships(input) {
             input.storeFacts.canonicalRemote !== input.storeFacts.originUrl) {
             storeStatus.push(makeStoreDiagnostic('info', 'store_remote_divergence', `The store.yaml remote (${sanitizeInline(input.storeFacts.canonicalRemote, 200)}) differs from the checkout's origin (${sanitizeInline(input.storeFacts.originUrl, 200)}).`, { target: 'store.metadata' }));
         }
+        // Checkout behind its upstream tracking ref: a read-only staleness
+        // signal, not a version pin — OpenSpec never syncs stores, so this
+        // compares against the local upstream ref, not the live remote.
+        // Behind means teammates on newer commits may resolve different specs.
+        // Ahead-only is normal (OpenSpec never pushes stores), so it stays quiet.
+        const drift = input.storeFacts.drift;
+        if (drift && drift.behind > 0) {
+            const behindCommits = `${drift.behind} commit${drift.behind === 1 ? '' : 's'}`;
+            storeStatus.push(makeStoreDiagnostic('info', 'store_checkout_drift', drift.ahead > 0
+                ? `This store checkout has diverged from its upstream tracking branch (${drift.behind} behind, ${drift.ahead} ahead); teammates on newer commits may resolve different specs.`
+                : `This store checkout is ${behindCommits} behind its upstream tracking branch; teammates on newer commits may resolve different specs.`, { target: 'store.git' }));
+        }
         store = {
             id: input.storeFacts.id,
             metadata: {
@@ -47,6 +59,7 @@ export function inspectRelationships(input) {
                     : {}),
             },
             ...(input.storeFacts.originUrl ? { origin_url: input.storeFacts.originUrl } : {}),
+            ...(drift ? { drift } : {}),
             status: storeStatus,
         };
     }

package/dist/core/root-selection.d.ts

@@ -7,8 +7,11 @@
  * - `--store <id>` selects a registered store's root.
  * - Without `--store`, the nearest ancestor containing `openspec/` wins.
  *   Leftover workspace view state is never considered a root here.
- * - With no nearest root, registered stores produce a selection hint error;
- *   otherwise commands may treat the current directory as an implicit root.
+ * - With no nearest root, a global `defaultStore` (if set) is the last
+ *   machine-level fallback before the selection hint error.
+ * - With no nearest root and no default, registered stores produce a
+ *   selection hint error; otherwise commands may treat the current
+ *   directory as an implicit root.
  *
  * Diagnostic codes reuse the store taxonomy where an error passes
  * through unchanged (`invalid_store_id`, metadata parse failures);
@@ -19,7 +22,7 @@
  * `no_openspec_root`).
  */
 import { type PlanningHome } from './planning-home.js';
-export type OpenSpecRootSource = 'store' | 'declared' | 'nearest' | 'implicit';
+export type OpenSpecRootSource = 'store' | 'declared' | 'global_default' | 'nearest' | 'implicit';
 export interface StoreSelectorOptions {
     store?: string;
     storePath?: string;
@@ -84,9 +87,9 @@ export interface RootOutput {
 }
 export declare function toRootOutput(root: ResolvedOpenSpecRoot): RootOutput;
 /**
- * A store-selected root — explicit `--store` or the declared fallback.
- * Cross-root behavior (absolute paths, --store hints, suppressed
- * noun-form suggestions) keys on this, never on `source` directly.
+ * A store-selected root — explicit `--store`, a declared pointer, or the
+ * global default. Cross-root behavior (absolute paths, --store hints,
+ * suppressed noun-form suggestions) keys on this, never on `source` directly.
  */
 export declare function isStoreSelectedRoot(root: ResolvedOpenSpecRoot): root is ResolvedOpenSpecRoot & {
     storeId: string;

package/dist/core/root-selection.js

@@ -7,8 +7,11 @@
  * - `--store <id>` selects a registered store's root.
  * - Without `--store`, the nearest ancestor containing `openspec/` wins.
  *   Leftover workspace view state is never considered a root here.
- * - With no nearest root, registered stores produce a selection hint error;
- *   otherwise commands may treat the current directory as an implicit root.
+ * - With no nearest root, a global `defaultStore` (if set) is the last
+ *   machine-level fallback before the selection hint error.
+ * - With no nearest root and no default, registered stores produce a
+ *   selection hint error; otherwise commands may treat the current
+ *   directory as an implicit root.
  *
  * Diagnostic codes reuse the store taxonomy where an error passes
  * through unchanged (`invalid_store_id`, metadata parse failures);
@@ -26,6 +29,7 @@ import { getStoreRootForBackend } from './store/registry.js';
 import { inspectOpenSpecRoot } from './openspec-root.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
+import { getGlobalConfig } from './global-config.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 export class RootSelectionError extends Error {
     diagnostic;
@@ -221,6 +225,32 @@ async function resolveNearestOrDeclaredRoot(nearestRoot, globalDataDir) {
         throw error;
     }
 }
+/**
+ * The machine-level fallback: the global `defaultStore` resolved as a root,
+ * with its own provenance (`global_default`) so JSON surfaces can tell a
+ * machine-wide default from a repo's `store:` pointer. Mirrors the
+ * declared-pointer catch — a stale or unregistered id degrades to the
+ * underlying error, reshaped to point at clearing the global default
+ * rather than passing --store.
+ */
+async function resolveDefaultStoreRoot(id, globalDataDir) {
+    try {
+        return await resolveStoreRoot(id, globalDataDir, 'global_default');
+    }
+    catch (error) {
+        if (error instanceof RootSelectionError) {
+            const staleFix = error.diagnostic.code === 'unknown_store' ||
+                error.diagnostic.code === 'no_registered_stores'
+                ? `Register the store (openspec store register <path> --id ${id}) or clear the stale global default (openspec config unset defaultStore).`
+                : error.diagnostic.fix;
+            throw new RootSelectionError(`Global defaultStore '${id}': ${error.message}`, error.diagnostic.code, {
+                ...(error.diagnostic.target ? { target: error.diagnostic.target } : {}),
+                ...(staleFix ? { fix: staleFix } : {}),
+            });
+        }
+        throw error;
+    }
+}
 export async function resolveOpenSpecRoot(options = {}) {
     if (options.storePath !== undefined) {
         throw new RootSelectionError('--store-path is not supported. Register the path with openspec store register <path>, then select it with --store <id>.', 'store_path_not_supported', {
@@ -236,6 +266,13 @@ export async function resolveOpenSpecRoot(options = {}) {
     if (nearestRoot) {
         return resolveNearestOrDeclaredRoot(nearestRoot, options.globalDataDir);
     }
+    // Machine-level fallback: a global defaultStore is consulted only after
+    // --store, the nearest local root, and project-level pointers have all
+    // failed to resolve — it changes the failure path, never the precedence.
+    const defaultStore = getGlobalConfig().defaultStore;
+    if (defaultStore) {
+        return resolveDefaultStoreRoot(defaultStore, options.globalDataDir);
+    }
     let registry;
     try {
         registry = await readStoreRegistryState(options.globalDataDir ? { globalDataDir: options.globalDataDir } : {});
@@ -265,9 +302,9 @@ export function toRootOutput(root) {
     };
 }
 /**
- * A store-selected root — explicit `--store` or the declared fallback.
- * Cross-root behavior (absolute paths, --store hints, suppressed
- * noun-form suggestions) keys on this, never on `source` directly.
+ * A store-selected root — explicit `--store`, a declared pointer, or the
+ * global default. Cross-root behavior (absolute paths, --store hints,
+ * suppressed noun-form suggestions) keys on this, never on `source` directly.
  */
 export function isStoreSelectedRoot(root) {
     return root.storeId !== undefined;

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

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

@@ -32,9 +32,13 @@ export interface ToolVersionStatus {
     toolId: string;
     /** The tool's display name */
     toolName: string;
-    /** Whether the tool has any skills configured */
+    /** Whether the tool has any skills or commands configured */
     configured: boolean;
-    /** The generatedBy version found in the skill files, or null if not found */
+    /**
+     * The generatedBy version recorded in the tool's skill files. For a tool that
+     * has commands but no skills, the current version when the command files match
+     * what would be generated now. Null when neither says the files are current.
+     */
     generatedByVersion: string | null;
     /** Whether the tool needs updating (version mismatch or missing) */
     needsUpdate: boolean;
@@ -47,6 +51,19 @@ export declare function getToolsWithSkillsDir(): string[];
  * Checks which skill files exist for a tool.
  */
 export declare function getToolSkillStatus(projectRoot: string, toolId: string): ToolSkillStatus;
+/**
+ * Checks whether a tool has at least one generated OpenSpec command file.
+ */
+export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string): boolean;
+/**
+ * Checks whether command files for a tool on disk match current generated command contents.
+ *
+ * Command files carry no version stamp, so content equality is the only available
+ * "is this current?" signal for a commands-only install.
+ */
+export declare function areCommandFilesUpToDate(projectRoot: string, toolId: string, options?: {
+    workflows?: readonly string[];
+}): boolean;
 /**
  * Gets the skill status for all tools with skillsDir configured.
  */
@@ -57,11 +74,14 @@ export declare function getToolStates(projectRoot: string): Map<string, ToolSkil
  */
 export declare function extractGeneratedByVersion(skillFilePath: string): string | null;
 /**
- * Gets version status for a tool by reading the first available skill file.
+ * Gets version status for a tool by reading its skill files, falling back to a
+ * command-content fingerprint for installs that have commands but no skills.
  */
-export declare function getToolVersionStatus(projectRoot: string, toolId: string, currentVersion: string): ToolVersionStatus;
+export declare function getToolVersionStatus(projectRoot: string, toolId: string, currentVersion: string, options?: {
+    workflows?: readonly string[];
+}): ToolVersionStatus;
 /**
- * Gets all configured tools in the project.
+ * Gets all configured tools in the project (configured via skills or commands).
  */
 export declare function getConfiguredTools(projectRoot: string): string[];
 /**