@codewalla_india/openspec 1.3.1 → 1.3.2

package/dist/utils/change-utils.js

@@ -1,32 +1,43 @@
 import path from 'path';
 import { FileSystemUtils } from './file-system.js';
 import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
+import { formatLocalDate } from './date.js';
 import { readProjectConfig } from '../core/project-config.js';
+import { isKebabId } from '../core/id.js';
 const DEFAULT_SCHEMA = 'spec-driven';
 /**
  * Validates that a change name follows kebab-case conventions.
  *
- * Valid names:
- * - Start with a lowercase letter
+ * Uses OpenSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
  * - Contain only lowercase letters, numbers, and hyphens
- * - Do not start or end with a hyphen
- * - Do not contain consecutive hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
  *
  * @param name - The change name to validate
  * @returns Validation result with `valid: true` or `valid: false` with an error message
  *
  * @example
  * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
  * validateChangeName('Add-Auth') // { valid: false, error: '...' }
  */
 export function validateChangeName(name) {
-    // Pattern: starts with lowercase letter, followed by lowercase letters/numbers,
-    // optionally followed by hyphen + lowercase letters/numbers (repeatable)
-    const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
     if (!name) {
         return { valid: false, error: 'Change name cannot be empty' };
     }
-    if (!kebabCasePattern.test(name)) {
+    // Filesystem directory components cap at 255 bytes and archive prepends a
+    // date prefix; bounding here turns the failure into a validation message
+    // instead of a raw ENAMETOOLONG from mkdir.
+    if (name.length > 200) {
+        return { valid: false, error: 'Change name is too long (200 characters max)' };
+    }
+    if (!isKebabId(name)) {
         // Provide specific error messages for common mistakes
         if (/[A-Z]/.test(name)) {
             return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
@@ -49,9 +60,6 @@ export function validateChangeName(name) {
         if (/[^a-z0-9-]/.test(name)) {
             return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
         }
-        if (/^[0-9]/.test(name)) {
-            return { valid: false, error: 'Change name must start with a letter' };
-        }
         return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, refactor-db)' };
     }
     return { valid: true };
@@ -127,10 +135,9 @@ export async function createChange(projectRoot, name, options = {}) {
         await FileSystemUtils.writeFile(configPath, `schema: ${defaultSchema}\n`);
     }
     // Write metadata file with schema and creation date
-    const today = new Date().toISOString().split('T')[0];
     writeChangeMetadata(changeDir, {
         schema: schemaName,
-        created: today,
+        created: formatLocalDate(),
         ...options.metadata,
     }, projectRoot);
     return { schema: schemaName, changeDir };

package/dist/utils/ci.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=ci.d.ts.map

package/dist/utils/ci.js

@@ -0,0 +1,16 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+const CI_DISABLED_VALUES = new Set(['', 'false', '0', 'no', 'off']);
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export function isCiEnvironment(env = process.env) {
+    const value = env.CI;
+    return value !== undefined && !CI_DISABLED_VALUES.has(value.trim().toLowerCase());
+}
+//# sourceMappingURL=ci.js.map

package/dist/utils/command-references.d.ts

@@ -3,16 +3,102 @@
  *
  * Utilities for transforming command references to tool-specific formats.
  */
+import type { CommandSurfaceCapability } from '../core/command-surface.js';
+import type { CommandInvocation } from '../core/command-generation/invocation.js';
 /**
- * Transforms colon-based command references to hyphen-based format.
- * Converts `/opsx:` patterns to `/opsx-` for tools that use hyphen syntax.
+ * Rewrites the canonical `/opsx:<command>` references that command bodies and
+ * skill templates are authored with into the form one tool actually registers
+ * — `/opsx-<command>` for tools that name the command by filename,
+ * `@opsx-<command>` for Amazon Q's prompt library.
+ *
+ * Only known command ids are rewritten, matching how
+ * `transformToSkillReferences` leaves unrecognized references alone, so a
+ * mistyped or invented `/opsx:<something>` is left as written rather than
+ * silently reshaped into a command that does not exist either.
  *
  * @param text - The text containing command references
- * @returns Text with command references transformed to hyphen format
+ * @param invocation - The tool's invocation, from resolveCommandInvocation()
+ * @returns Text with command references spelled the tool's way
  *
  * @example
- * transformToHyphenCommands('/opsx:new') // returns '/opsx-new'
- * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '/' }) // '/opsx-new'
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '@' }) // '@opsx-new'
+ */
+export declare function transformCommandInvocations(text: string, invocation: CommandInvocation): string;
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export declare function usesNaturalLanguageSkillReferences(toolId: string): boolean;
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export declare function transformToCodexCompatibleSkillReferences(text: string): string;
+/**
+ * Transforms command references to skill references using the default `/`
+ * invocation prefix. Converts `/opsx:<command>` patterns to
+ * `/openspec-<skill>` so that generated skills do not reference commands
+ * that were never generated. Used for channels that are not tied to one
+ * tool (e.g. the skills.sh distribution); tool-targeted generation should
+ * go through getSkillReferenceTransformer instead.
+ *
+ * Unknown command references are left unchanged.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to skill references
+ *
+ * @example
+ * transformToSkillReferences('/opsx:apply') // returns '/openspec-apply-change'
+ * transformToSkillReferences('Use /opsx:archive next') // returns 'Use /openspec-archive-change next'
+ */
+export declare function transformToSkillReferences(text: string): string;
+/**
+ * Returns the skill-reference transformer for a specific tool, honoring the
+ * tool's documented skill invocation syntax (e.g. Kimi Code's
+ * `/skill:openspec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the openspec-propose skill"); everything else
+ * falls back to the default `/openspec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
+ * @returns A transformer converting `/opsx:*` references to skill invocations
+ */
+export declare function getSkillReferenceTransformer(toolId: string): (text: string) => string;
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skill references are used whenever the tool ends up without `/opsx:*`
+ * commands — because delivery is skills-only, because the tool has no command
+ * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
+ * because the tool invokes skills directly and OpenSpec generates no command
+ * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * never point at commands that were not generated.
+ *
+ * When commands are generated, the spelling follows the tool's invocation: a
+ * `flat` adapter names the command by filename (`.cursor/commands/opsx-apply.md`
+ * → `/opsx-apply`), a `namespaced` adapter puts it in an `opsx/` directory
+ * (`.claude/commands/opsx/apply.md` → `/opsx:apply`), and a non-slash prefix
+ * wraps it further (`.amazonq/prompts/opsx-apply.md` → `@opsx-apply`). Passing
+ * the invocation in keeps this module free of a hand-maintained tool list —
+ * the list drifted and left 16 tools advertising commands their palettes never
+ * registered (#727, #1307).
+ *
+ * Devin is the one tool that takes skill references even though its commands
+ * are generated: only Devin Desktop reads `.devin/workflows/`, so a workflow
+ * reference is dead text for anyone on Devin Local, while the `/openspec-*`
+ * skills work on both agents. Under commands-only delivery there are no Devin
+ * skills to point at, so it falls through to the invocation rewrite below and
+ * gets the `/opsx-<id>` form its workflow filenames register.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @param capability - The tool's command surface capability
+ * @param invocation - How the tool's generated commands are invoked, from
+ *        resolveCommandInvocation(); undefined for tools with no command
+ *        adapter. Required rather than optional so a caller that forgets it
+ *        fails to compile instead of silently getting the canonical form.
+ * @returns The transformer to pass to generateSkillContent, or undefined when
+ *          the tool already answers to the canonical `/opsx:<id>`
  */
-export declare function transformToHyphenCommands(text: string): string;
+export declare function getTransformerForTool(toolId: string, delivery: 'both' | 'skills' | 'commands', capability: CommandSurfaceCapability, invocation: CommandInvocation | undefined): ((text: string) => string) | undefined;
 //# sourceMappingURL=command-references.d.ts.map

package/dist/utils/command-references.js

@@ -3,18 +3,191 @@
  *
  * Utilities for transforming command references to tool-specific formats.
  */
+// Value import of a pure, dependency-free helper: invocation.ts imports only
+// `path` and a type, so this does not close the cycle the note above guards.
+import { formatCommandInvocation, needsInvocationRewrite, } from '../core/command-generation/invocation.js';
 /**
- * Transforms colon-based command references to hyphen-based format.
- * Converts `/opsx:` patterns to `/opsx-` for tools that use hyphen syntax.
+ * Rewrites the canonical `/opsx:<command>` references that command bodies and
+ * skill templates are authored with into the form one tool actually registers
+ * — `/opsx-<command>` for tools that name the command by filename,
+ * `@opsx-<command>` for Amazon Q's prompt library.
+ *
+ * Only known command ids are rewritten, matching how
+ * `transformToSkillReferences` leaves unrecognized references alone, so a
+ * mistyped or invented `/opsx:<something>` is left as written rather than
+ * silently reshaped into a command that does not exist either.
+ *
+ * @param text - The text containing command references
+ * @param invocation - The tool's invocation, from resolveCommandInvocation()
+ * @returns Text with command references spelled the tool's way
+ *
+ * @example
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '/' }) // '/opsx-new'
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '@' }) // '@opsx-new'
+ */
+export function transformCommandInvocations(text, invocation) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => commandId in COMMAND_TO_SKILL_NAME
+        ? formatCommandInvocation(invocation, commandId)
+        : match);
+}
+/**
+ * Maps command short names to their skill names.
+ * Keep in sync with WORKFLOW_TO_SKILL_DIR, which exists in both
+ * src/core/profile-sync-drift.ts (exported) and src/core/init.ts (local copy).
+ */
+const COMMAND_TO_SKILL_NAME = {
+    'explore': 'openspec-explore',
+    'new': 'openspec-new-change',
+    'continue': 'openspec-continue-change',
+    'apply': 'openspec-apply-change',
+    'update': 'openspec-update-change',
+    'ff': 'openspec-ff-change',
+    'sync': 'openspec-sync-specs',
+    'archive': 'openspec-archive-change',
+    'bulk-archive': 'openspec-bulk-archive-change',
+    'verify': 'openspec-verify-change',
+    'onboard': 'openspec-onboard',
+    'propose': 'openspec-propose',
+};
+/**
+ * Tools whose skill invocation uses a non-default prefix. The default is `/`
+ * (e.g. `/openspec-propose`); Kimi Code invokes skills as `/skill:<name>` and
+ * Codex CLI as `$<name>` — a `/<name>` form Codex does not recognize
+ * (see docs/supported-tools.md).
+ */
+const SKILL_INVOCATION_PREFIX = {
+    kimi: '/skill:',
+    codex: '$',
+};
+/**
+ * Tools that have no slash-command surface at all: skills are matched
+ * automatically or invoked by natural-language prompts, never by typing a
+ * `/<name>` command. Rovo Dev CLI is such a tool — `/skills` only manages
+ * skills, and any `/openspec-*` form would be a dead command (see
+ * docs/supported-tools.md). References for these tools are spelled as prose
+ * ("the openspec-propose skill") so generated content never tells the user to
+ * type a command their CLI does not register.
+ */
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev']);
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export function usesNaturalLanguageSkillReferences(toolId) {
+    return NATURAL_LANGUAGE_SKILL_TOOLS.has(toolId);
+}
+function replaceCommandsWithNaturalLanguageSkillReferences(text) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `the ${skillName} skill`;
+    });
+}
+function replaceCommandsWithSkillReferences(text, prefix) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `${prefix}${skillName}`;
+    });
+}
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export function transformToCodexCompatibleSkillReferences(text) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined
+            ? match
+            : `$${skillName} (Codex) or /${skillName} (other agents)`;
+    });
+}
+/**
+ * Transforms command references to skill references using the default `/`
+ * invocation prefix. Converts `/opsx:<command>` patterns to
+ * `/openspec-<skill>` so that generated skills do not reference commands
+ * that were never generated. Used for channels that are not tied to one
+ * tool (e.g. the skills.sh distribution); tool-targeted generation should
+ * go through getSkillReferenceTransformer instead.
+ *
+ * Unknown command references are left unchanged.
  *
  * @param text - The text containing command references
- * @returns Text with command references transformed to hyphen format
+ * @returns Text with command references transformed to skill references
  *
  * @example
- * transformToHyphenCommands('/opsx:new') // returns '/opsx-new'
- * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
+ * transformToSkillReferences('/opsx:apply') // returns '/openspec-apply-change'
+ * transformToSkillReferences('Use /opsx:archive next') // returns 'Use /openspec-archive-change next'
+ */
+export function transformToSkillReferences(text) {
+    return replaceCommandsWithSkillReferences(text, '/');
+}
+/**
+ * Returns the skill-reference transformer for a specific tool, honoring the
+ * tool's documented skill invocation syntax (e.g. Kimi Code's
+ * `/skill:openspec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the openspec-propose skill"); everything else
+ * falls back to the default `/openspec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
+ * @returns A transformer converting `/opsx:*` references to skill invocations
+ */
+export function getSkillReferenceTransformer(toolId) {
+    if (usesNaturalLanguageSkillReferences(toolId)) {
+        return replaceCommandsWithNaturalLanguageSkillReferences;
+    }
+    const prefix = SKILL_INVOCATION_PREFIX[toolId];
+    if (prefix === undefined) {
+        return transformToSkillReferences;
+    }
+    return (text) => replaceCommandsWithSkillReferences(text, prefix);
+}
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skill references are used whenever the tool ends up without `/opsx:*`
+ * commands — because delivery is skills-only, because the tool has no command
+ * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
+ * because the tool invokes skills directly and OpenSpec generates no command
+ * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * never point at commands that were not generated.
+ *
+ * When commands are generated, the spelling follows the tool's invocation: a
+ * `flat` adapter names the command by filename (`.cursor/commands/opsx-apply.md`
+ * → `/opsx-apply`), a `namespaced` adapter puts it in an `opsx/` directory
+ * (`.claude/commands/opsx/apply.md` → `/opsx:apply`), and a non-slash prefix
+ * wraps it further (`.amazonq/prompts/opsx-apply.md` → `@opsx-apply`). Passing
+ * the invocation in keeps this module free of a hand-maintained tool list —
+ * the list drifted and left 16 tools advertising commands their palettes never
+ * registered (#727, #1307).
+ *
+ * Devin is the one tool that takes skill references even though its commands
+ * are generated: only Devin Desktop reads `.devin/workflows/`, so a workflow
+ * reference is dead text for anyone on Devin Local, while the `/openspec-*`
+ * skills work on both agents. Under commands-only delivery there are no Devin
+ * skills to point at, so it falls through to the invocation rewrite below and
+ * gets the `/opsx-<id>` form its workflow filenames register.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @param capability - The tool's command surface capability
+ * @param invocation - How the tool's generated commands are invoked, from
+ *        resolveCommandInvocation(); undefined for tools with no command
+ *        adapter. Required rather than optional so a caller that forgets it
+ *        fails to compile instead of silently getting the canonical form.
+ * @returns The transformer to pass to generateSkillContent, or undefined when
+ *          the tool already answers to the canonical `/opsx:<id>`
  */
-export function transformToHyphenCommands(text) {
-    return text.replace(/\/opsx:/g, '/opsx-');
+export function getTransformerForTool(toolId, delivery, capability, invocation) {
+    if (delivery === 'skills' || capability !== 'adapter-backed') {
+        return toolId === 'codex'
+            ? transformToCodexCompatibleSkillReferences
+            : getSkillReferenceTransformer(toolId);
+    }
+    if (toolId === 'devin' && delivery === 'both') {
+        return getSkillReferenceTransformer(toolId);
+    }
+    if (invocation !== undefined && needsInvocationRewrite(invocation)) {
+        return (text) => transformCommandInvocations(text, invocation);
+    }
+    return undefined;
 }
 //# sourceMappingURL=command-references.js.map

package/dist/utils/date.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a date using the effective local time zone of the Node.js process.
+ *
+ * The result is locale-independent and suitable for date-only metadata and
+ * path prefixes.
+ */
+export declare function formatLocalDate(date?: Date): string;
+//# sourceMappingURL=date.d.ts.map

package/dist/utils/date.js

@@ -0,0 +1,13 @@
+/**
+ * Formats a date using the effective local time zone of the Node.js process.
+ *
+ * The result is locale-independent and suitable for date-only metadata and
+ * path prefixes.
+ */
+export function formatLocalDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+//# sourceMappingURL=date.js.map

package/dist/utils/file-system.d.ts

@@ -9,6 +9,16 @@ export declare class FileSystemUtils {
      * Falls back to path.resolve() so callers can still produce a stable absolute path.
      */
     static canonicalizeExistingPath(targetPath: string): string;
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
+    static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
+    private static isPathWithin;
+    private static canonicalizePotentialPath;
     private static isWindowsBasePath;
     private static normalizeSegments;
     static joinPath(basePath: string, ...segments: string[]): string;

package/dist/utils/file-system.js

@@ -87,6 +87,76 @@ export class FileSystemUtils {
             }
         }
     }
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory, targetPath) {
+        const resolvedDirectory = path.resolve(allowedDirectory);
+        const resolvedTarget = path.resolve(targetPath);
+        if (!this.isPathWithin(resolvedDirectory, resolvedTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+        const canonicalDirectory = this.canonicalizePotentialPath(resolvedDirectory);
+        const canonicalTarget = this.canonicalizePotentialPath(resolvedTarget);
+        if (!this.isPathWithin(canonicalDirectory, canonicalTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+    }
+    static resolveProjectArtifactPath(projectPath, artifactPath) {
+        if (path.isAbsolute(artifactPath)) {
+            throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);
+        }
+        const targetPath = path.join(projectPath, artifactPath);
+        this.assertPathWithin(projectPath, targetPath);
+        return targetPath;
+    }
+    static assertProjectArtifactPath(projectPath, targetPath) {
+        this.assertPathWithin(projectPath, targetPath);
+    }
+    static isPathWithin(allowedDirectory, targetPath) {
+        const relative = path.relative(allowedDirectory, targetPath);
+        return (relative === '' ||
+            (relative !== '..' &&
+                !relative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relative)));
+    }
+    static canonicalizePotentialPath(targetPath) {
+        let existingPath = targetPath;
+        const missingSegments = [];
+        while (true) {
+            try {
+                // lstat distinguishes a missing path from a dangling symlink. A
+                // dangling link cannot be proven confined, so realpath must fail it.
+                nodeFs.lstatSync(existingPath);
+                const canonicalExisting = nodeFs.realpathSync.native(existingPath);
+                return path.resolve(canonicalExisting, ...missingSegments);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOENT') {
+                    throw error;
+                }
+                try {
+                    if (nodeFs.lstatSync(existingPath).isSymbolicLink()) {
+                        throw new Error(`Cannot verify dangling symbolic link: ${existingPath}`);
+                    }
+                }
+                catch (lstatError) {
+                    if (lstatError.code !== 'ENOENT') {
+                        throw lstatError;
+                    }
+                }
+                const parent = path.dirname(existingPath);
+                if (parent === existingPath) {
+                    throw new Error(`Cannot resolve an existing parent for ${targetPath}`);
+                }
+                missingSegments.unshift(path.basename(existingPath));
+                existingPath = parent;
+            }
+        }
+    }
     static isWindowsBasePath(basePath) {
         return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
     }

package/dist/utils/index.d.ts

@@ -2,5 +2,5 @@ export { validateChangeName, createChange } from './change-utils.js';
 export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
 export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
-export { transformToHyphenCommands } from './command-references.js';
+export { transformCommandInvocations, transformToSkillReferences, getSkillReferenceTransformer, getTransformerForTool, } from './command-references.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -5,5 +5,5 @@ export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, valida
 // File system utilities
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 // Command reference utilities
-export { transformToHyphenCommands } from './command-references.js';
+export { transformCommandInvocations, transformToSkillReferences, getSkillReferenceTransformer, getTransformerForTool, } from './command-references.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/interactive.d.ts

@@ -15,4 +15,27 @@ export type InteractiveOptions = {
  */
 export declare function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean;
 export declare function isInteractive(value?: boolean | InteractiveOptions): boolean;
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | openspec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty.
+ */
+export declare function isNonInteractivePromptError(error: unknown, value?: boolean | InteractiveOptions): boolean;
 //# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -18,4 +18,36 @@ export function isInteractive(value) {
         return false;
     return !!process.stdin.isTTY;
 }
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | openspec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty.
+ */
+export function isNonInteractivePromptError(error, value) {
+    if (!(error instanceof Error))
+        return false;
+    const failedPrompt = error.name === 'ExitPromptError' || error.message.includes('force closed the prompt');
+    if (!failedPrompt)
+        return false;
+    if (error.message.includes('SIGINT'))
+        return false;
+    return !isInteractive(value);
+}
 //# sourceMappingURL=interactive.js.map

package/dist/utils/item-discovery.d.ts

@@ -1,4 +1,23 @@
+/**
+ * Returns the ids of active changes: every directory under openspec/changes/
+ * except the archive and hidden directories.
+ *
+ * A change is resolved by its directory alone - the same rule `list`,
+ * `status`, `instructions` and `validate` use (`getAvailableChanges`).
+ * Requiring proposal.md here made `openspec show` and shell completion miss
+ * changes those commands resolve: `openspec new change <name>` scaffolds only
+ * `.openspec.yaml`, and a custom schema need not define a proposal artifact at
+ * all (#1161).
+ */
 export declare function getActiveChangeIds(root?: string): Promise<string[]>;
 export declare function getSpecIds(root?: string): Promise<string[]>;
+/**
+ * Returns the ids of archived changes: every directory under
+ * openspec/changes/archive/ except hidden directories.
+ *
+ * Resolved by directory for the same reason as `getActiveChangeIds`: a change
+ * archived from a schema without a proposal artifact has no proposal.md, and
+ * gating on it hid those entries from shell completion.
+ */
 export declare function getArchivedChangeIds(root?: string): Promise<string[]>;
 //# sourceMappingURL=item-discovery.d.ts.map