@fission-ai/openspec 1.6.0 → 1.7.0

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/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[];
 /**

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

@@ -6,6 +6,10 @@
 import path from 'path';
 import * as fs from 'fs';
 import { AI_TOOLS } 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';
 /**
  * Names of skill directories created by openspec init.
  */
@@ -68,6 +72,88 @@ export function getToolSkillStatus(projectRoot, toolId) {
         skillCount,
     };
 }
+/**
+ * Checks whether a tool has at least one generated OpenSpec command file.
+ */
+export function toolHasAnyConfiguredCommand(projectPath, toolId) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    for (const commandId of COMMAND_IDS) {
+        const cmdPath = adapter.getFilePath(commandId);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+        if (fs.existsSync(fullPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalizes checkout artifacts that are not real content drift: a UTF-8 BOM and
+ * CRLF line endings, which a Windows clone with `core.autocrlf` reintroduces on
+ * every checkout of committed command files.
+ */
+function normalizeCommandContent(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}
+/**
+ * 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 function areCommandFilesUpToDate(projectRoot, toolId, options) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    let workflows;
+    if (options?.workflows) {
+        workflows = options.workflows;
+    }
+    else {
+        try {
+            const globalCfg = getGlobalConfig();
+            const profile = globalCfg.profile ?? 'core';
+            workflows = getProfileWorkflows(profile, globalCfg.workflows);
+        }
+        catch {
+            workflows = ALL_WORKFLOWS;
+        }
+    }
+    const knownWorkflows = workflows.filter((w) => ALL_WORKFLOWS.includes(w));
+    const commandContents = getCommandContents(knownWorkflows);
+    const generatedCommands = generateCommands(commandContents, adapter);
+    if (generatedCommands.length === 0) {
+        return false;
+    }
+    for (const cmd of generatedCommands) {
+        const cmdPath = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectRoot, cmd.path);
+        if (!fs.existsSync(cmdPath)) {
+            return false;
+        }
+        try {
+            const existingContent = fs.readFileSync(cmdPath, 'utf-8');
+            if (normalizeCommandContent(existingContent) !== normalizeCommandContent(cmd.fileContent)) {
+                return false;
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    // Also check no extra command files exist for deselected workflows
+    const desiredWorkflowSet = new Set(knownWorkflows);
+    for (const workflow of ALL_WORKFLOWS) {
+        if (desiredWorkflowSet.has(workflow))
+            continue;
+        const cmdPath = adapter.getFilePath(workflow);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectRoot, cmdPath);
+        if (fs.existsSync(fullPath)) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * Gets the skill status for all tools with skillsDir configured.
  */
@@ -109,9 +195,10 @@ export function extractGeneratedByVersion(skillFilePath) {
     }
 }
 /**
- * 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 function getToolVersionStatus(projectRoot, toolId, currentVersion) {
+export function getToolVersionStatus(projectRoot, toolId, currentVersion, options) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
     if (!tool?.skillsDir) {
         return {
@@ -124,7 +211,7 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion) {
     }
     const skillsDir = path.join(projectRoot, tool.skillsDir, 'skills');
     let generatedByVersion = null;
-    // Find the first skill file that exists and read its version
+    // 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)) {
@@ -132,7 +219,15 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion) {
             break;
         }
     }
-    const configured = getToolSkillStatus(projectRoot, toolId).configured;
+    const skillConfigured = getToolSkillStatus(projectRoot, toolId).configured;
+    const commandConfigured = toolHasAnyConfiguredCommand(projectRoot, toolId);
+    const configured = skillConfigured || commandConfigured;
+    // 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;
+    }
     const needsUpdate = configured && (generatedByVersion === null || generatedByVersion !== currentVersion);
     return {
         toolId,
@@ -143,11 +238,15 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion) {
     };
 }
 /**
- * Gets all configured tools in the project.
+ * Gets all configured tools in the project (configured via skills or commands).
  */
 export function getConfiguredTools(projectRoot) {
     return AI_TOOLS
-        .filter((t) => t.skillsDir && getToolSkillStatus(projectRoot, t.value).configured)
+        .filter((t) => {
+        if (!t.skillsDir)
+            return false;
+        return getToolSkillStatus(projectRoot, t.value).configured || toolHasAnyConfiguredCommand(projectRoot, t.value);
+    })
         .map((t) => t.value);
 }
 /**

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

@@ -5,28 +5,12 @@
  * Applies delta specs from a change to main specs without archiving.
  */
 export interface SpecUpdate {
+    /** Capability id relative to the specs root, forward-slash separated (e.g. "web" or "platform/session-layout"). */
+    id: string;
     source: string;
     target: string;
     exists: boolean;
 }
-export interface ApplyResult {
-    capability: string;
-    added: number;
-    modified: number;
-    removed: number;
-    renamed: number;
-}
-export interface SpecsApplyOutput {
-    changeName: string;
-    capabilities: ApplyResult[];
-    totals: {
-        added: number;
-        modified: number;
-        removed: number;
-        renamed: number;
-    };
-    noChanges: boolean;
-}
 /**
  * Find all delta spec files that need to be applied from a change.
  */
@@ -45,6 +29,7 @@ export declare function buildUpdatedSpec(update: SpecUpdate, changeName: string,
         removed: number;
         renamed: number;
     };
+    warnings: string[];
 }>;
 /**
  * Write an updated spec to disk.
@@ -59,20 +44,10 @@ export declare function writeUpdatedSpec(update: SpecUpdate, rebuilt: string, co
     displayPath?: string;
 }): Promise<void>;
 /**
- * Build a skeleton spec for new capabilities.
+ * Build a skeleton spec for new capabilities. When the delta spec authored a
+ * `## Purpose`, carry it over instead of the TBD placeholder (#1413) - archive
+ * invents the Purpose for a brand-new main spec either way, and the author's
+ * own wording beats a placeholder they then have to hand-edit.
  */
-export declare function buildSpecSkeleton(specFolderName: string, changeName: string): string;
-/**
- * Apply all delta specs from a change to main specs.
- *
- * @param projectRoot - The project root directory
- * @param changeName - The name of the change to apply
- * @param options - Options for the operation
- * @returns Result of the operation with counts
- */
-export declare function applySpecs(projectRoot: string, changeName: string, options?: {
-    dryRun?: boolean;
-    skipValidation?: boolean;
-    silent?: boolean;
-}): Promise<SpecsApplyOutput>;
+export declare function buildSpecSkeleton(specFolderName: string, changeName: string, purpose?: string): string;
 //# sourceMappingURL=specs-apply.d.ts.map