@fission-ai/openspec 1.6.0 → 1.7.0

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

@@ -3,16 +3,90 @@
  *
  * 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;
+/**
+ * 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`). Falls back to the default `/openspec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe')
+ * @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,149 @@
  *
  * 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
- * @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 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: '$',
+};
+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}`;
+    });
+}
+/**
+ * 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 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`). Falls back to the default `/openspec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe')
+ * @returns A transformer converting `/opsx:*` references to skill invocations
+ */
+export function getSkillReferenceTransformer(toolId) {
+    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 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/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/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

package/dist/utils/item-discovery.js

@@ -1,23 +1,25 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import { discoverSpecFiles } from './spec-discovery.js';
+/**
+ * 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 async function getActiveChangeIds(root = process.cwd()) {
     const changesPath = path.join(root, 'openspec', 'changes');
     try {
         const entries = await fs.readdir(changesPath, { withFileTypes: true });
-        const result = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive')
-                continue;
-            const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
-            try {
-                await fs.access(proposalPath);
-                result.push(entry.name);
-            }
-            catch {
-                // skip directories without proposal.md
-            }
-        }
-        return result.sort();
+        return entries
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive' && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort();
     }
     catch {
         return [];
@@ -25,45 +27,25 @@ export async function getActiveChangeIds(root = process.cwd()) {
 }
 export async function getSpecIds(root = process.cwd()) {
     const specsPath = path.join(root, 'openspec', 'specs');
-    const result = [];
-    try {
-        const entries = await fs.readdir(specsPath, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.'))
-                continue;
-            const specFile = path.join(specsPath, entry.name, 'spec.md');
-            try {
-                await fs.access(specFile);
-                result.push(entry.name);
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
-    catch {
-        // ignore
-    }
-    return result.sort();
+    const discovered = await discoverSpecFiles(specsPath);
+    return discovered.map((spec) => spec.id);
 }
+/**
+ * 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 async function getArchivedChangeIds(root = process.cwd()) {
     const archivePath = path.join(root, 'openspec', 'changes', 'archive');
     try {
         const entries = await fs.readdir(archivePath, { withFileTypes: true });
-        const result = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.'))
-                continue;
-            const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
-            try {
-                await fs.access(proposalPath);
-                result.push(entry.name);
-            }
-            catch {
-                // skip directories without proposal.md
-            }
-        }
-        return result.sort();
+        return entries
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort();
     }
     catch {
         return [];

package/dist/utils/shell-detection.d.ts

@@ -12,7 +12,7 @@ export interface ShellDetectionResult {
     detected: string | undefined;
 }
 /**
- * Detects the current user's shell based on environment variables
+ * Detects the current user's shell based on the parent process and environment
  *
  * @returns Detection result with supported shell and raw detected name
  */

package/dist/utils/shell-detection.js

@@ -1,21 +1,74 @@
+import { execFileSync } from 'node:child_process';
 /**
- * Detects the current user's shell based on environment variables
+ * Map a raw shell name/path to a supported shell, if any.
+ */
+function matchSupportedShell(name) {
+    // Match the executable basename exactly so lookalikes such as `fish-lsp` or
+    // `bash-language-server` don't get mistaken for the shell itself. Login
+    // shells report a leading dash (e.g. `-zsh`), so strip it first.
+    const executable = name.trim().toLowerCase().split('/').pop()?.replace(/^-/, '');
+    if (executable === 'zsh')
+        return 'zsh';
+    if (executable === 'bash')
+        return 'bash';
+    if (executable === 'fish')
+        return 'fish';
+    return undefined;
+}
+/**
+ * Detect the interactive shell from the parent process.
+ *
+ * `process.env.SHELL` is only the login shell, so users whose interactive shell
+ * differs from it (e.g. running fish while their login shell is bash) are
+ * misdetected. Inspecting the parent process reflects the shell that actually
+ * launched openspec. POSIX-only and best-effort — any failure returns undefined
+ * so the caller falls back to `$SHELL`.
+ *
+ * @returns The supported shell running as the parent process, or undefined
+ */
+function detectShellFromParentProcess() {
+    // `ps` is POSIX-only; Windows shells are handled via PSModulePath/COMSPEC.
+    if (process.platform === 'win32') {
+        return undefined;
+    }
+    const ppid = process.ppid;
+    if (!ppid || ppid <= 1) {
+        return undefined;
+    }
+    try {
+        const comm = execFileSync('ps', ['-p', String(ppid), '-o', 'comm='], {
+            encoding: 'utf8',
+            timeout: 1000,
+        }).trim();
+        if (!comm) {
+            return undefined;
+        }
+        // Only trust the parent process when it maps to a supported shell; an
+        // unrelated parent (node, npm, sudo, a pager) falls through to `$SHELL`.
+        return matchSupportedShell(comm);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Detects the current user's shell based on the parent process and environment
  *
  * @returns Detection result with supported shell and raw detected name
  */
 export function detectShell() {
-    // Try SHELL environment variable first (Unix-like systems)
+    // Prefer the actual running shell (parent process) over `$SHELL`, which only
+    // reflects the login shell and misses users whose interactive shell differs.
+    const parentShell = detectShellFromParentProcess();
+    if (parentShell) {
+        return { shell: parentShell, detected: parentShell };
+    }
+    // Try SHELL environment variable next (Unix-like systems)
     const shellPath = process.env.SHELL;
     if (shellPath) {
-        const shellName = shellPath.toLowerCase();
-        if (shellName.includes('zsh')) {
-            return { shell: 'zsh', detected: 'zsh' };
-        }
-        if (shellName.includes('bash')) {
-            return { shell: 'bash', detected: 'bash' };
-        }
-        if (shellName.includes('fish')) {
-            return { shell: 'fish', detected: 'fish' };
+        const supported = matchSupportedShell(shellPath);
+        if (supported) {
+            return { shell: supported, detected: supported };
         }
         // Shell detected but not supported
         // Extract shell name from path (e.g., /bin/tcsh -> tcsh)

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

@@ -0,0 +1,40 @@
+export interface DiscoveredSpec {
+    /** Spec id relative to the specs root, forward-slash separated on every platform (e.g. "web" or "platform/session-layout"). */
+    id: string;
+    /** Path to the spec.md file (absolute if the specs root is absolute). */
+    specFile: string;
+}
+/**
+ * Recursively discover every `spec.md` under a specs root, so both the flat
+ * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
+ * are found (#1353). A `spec.md` sitting directly in the root is ignored,
+ * matching the historical requirement that specs live in a capability folder.
+ * Dot-directories are skipped and symlinked directories are not followed.
+ * A symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the artifact
+ * graph's globs both count it as content, so dropping it here would silently
+ * lose the delta on archive; a dangling link is skipped. Results are sorted
+ * by id for deterministic output.
+ *
+ * A missing root (ENOENT) yields an empty list, but any other read failure
+ * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
+ * archive/apply merge path, silently dropping an unreadable capability would
+ * recreate the exact data-loss class #1353 is closing.
+ */
+export declare function discoverSpecFiles(specsRoot: string): Promise<DiscoveredSpec[]>;
+/**
+ * True when any regular non-dot file exists anywhere under the given
+ * directory. Used by validate/archive to detect content under a change's
+ * specs/ that contradicts a declared skip_specs marker - including files that
+ * discoverSpecFiles ignores (a root spec.md, stray non-spec.md notes), since
+ * anything there would be silently dropped or misread while the change claims
+ * to have nothing. Dot entries (.DS_Store, .gitkeep, dot-directories) are
+ * skipped to match discoverSpecFiles - they are invisible to every other
+ * code path, so they must not count as spec content. Symlinks DO count
+ * (without being followed): the artifact graph's globs follow them, so a
+ * symlinked spec would read as existing content while the change claims to
+ * have none - it contradicts the marker like any regular file. A missing
+ * directory returns false; other read failures are thrown for the caller to
+ * decide.
+ */
+export declare function hasAnyFileUnder(dirPath: string): Promise<boolean>;
+//# sourceMappingURL=spec-discovery.d.ts.map