@fission-ai/openspec 1.7.0 → 1.8.0

package/dist/utils/command-references.js

@@ -59,12 +59,47 @@ 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
@@ -88,12 +123,17 @@ export function transformToSkillReferences(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.
+ * `/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')
+ * @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;
@@ -138,7 +178,9 @@ export function getSkillReferenceTransformer(toolId) {
  */
 export function getTransformerForTool(toolId, delivery, capability, invocation) {
     if (delivery === 'skills' || capability !== 'adapter-backed') {
-        return getSkillReferenceTransformer(toolId);
+        return toolId === 'codex'
+            ? transformToCodexCompatibleSkillReferences
+            : getSkillReferenceTransformer(toolId);
     }
     if (toolId === 'devin' && delivery === 'both') {
         return getSkillReferenceTransformer(toolId);

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/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/spec-discovery.d.ts

@@ -10,10 +10,10 @@ export interface DiscoveredSpec {
  * 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.
+ * An in-capability 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 link outside its capability is
+ * rejected and a dangling link is skipped. Results are sorted by id.
  *
  * A missing root (ENOENT) yields an empty list, but any other read failure
  * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the

package/dist/utils/spec-discovery.js

@@ -1,15 +1,26 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+function assertDiscoveredSpecPath(specsRoot, capabilityDir, specFile) {
+    try {
+        FileSystemUtils.assertPathWithin(specsRoot, specFile);
+    }
+    catch {
+        // Direct capability directories may intentionally be external monorepo
+        // links. In that case, confine the file to the capability itself.
+        FileSystemUtils.assertPathWithin(capabilityDir, specFile);
+    }
+}
 /**
  * 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.
+ * An in-capability 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 link outside its capability is
+ * rejected and a dangling link is skipped. Results are sorted by id.
  *
  * A missing root (ENOENT) yields an empty list, but any other read failure
  * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
@@ -35,13 +46,15 @@ export async function discoverSpecFiles(specsRoot) {
                 await walk(path.join(dir, entry.name), [...segments, entry.name]);
             }
             else if (entry.name === 'spec.md' && segments.length > 0) {
+                const specFile = path.join(dir, entry.name);
                 if (entry.isFile()) {
-                    results.push({ id: segments.join('/'), specFile: path.join(dir, entry.name) });
+                    assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                    results.push({ id: segments.join('/'), specFile });
                 }
                 else if (entry.isSymbolicLink()) {
-                    const specFile = path.join(dir, entry.name);
                     try {
                         if ((await fs.stat(specFile)).isFile()) {
+                            assertDiscoveredSpecPath(specsRoot, dir, specFile);
                             results.push({ id: segments.join('/'), specFile });
                         }
                     }

package/dist/utils/task-progress.d.ts

@@ -1,3 +1,20 @@
+export interface ParsedTask {
+    /** Checkbox state: `[x]`/`[X]` is done, anything else is not. */
+    done: boolean;
+    /** Task text after the checkbox, trimmed (may be empty). */
+    description: string;
+}
+/**
+ * Parses every task line in a tasks file, in document order.
+ *
+ * Every line matching the pattern counts, wherever it sits - inside a code
+ * fence, an HTML comment or an indented block, as before. Skipping fenced
+ * checkboxes was tried and dropped: every rule for deciding which fence is
+ * "real" has an input where a stray or unbalanced ``` swallows genuine tasks.
+ * Counting a documented example as work is a loud, bypassable false positive;
+ * losing a real task is a silent one.
+ */
+export declare function parseTaskLines(content: string): ParsedTask[];
 export interface TaskProgress {
     total: number;
     completed: number;

package/dist/utils/task-progress.js

@@ -2,21 +2,49 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { resolveArtifactOutputs, resolveSchema } from '../core/artifact-graph/index.js';
 import { resolveSchemaForChange } from './change-metadata.js';
-const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
-const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
-export function countTasksFromContent(content) {
-    const lines = content.split('\n');
-    let total = 0;
-    let completed = 0;
-    for (const line of lines) {
-        if (line.match(TASK_PATTERN)) {
-            total++;
-            if (line.match(COMPLETED_TASK_PATTERN)) {
-                completed++;
-            }
+/**
+ * A Markdown task line: a `-`/`*` bullet carrying a `[ ]` or `[x]` checkbox.
+ *
+ * Leading whitespace is allowed so nested sub-tasks count like their parents.
+ * Anchoring at column 0 made `  - [ ] 1.1.1 ...` invisible to progress, to the
+ * apply task list, and to archive's incomplete-task check, so a change with
+ * unfinished sub-tasks reported "✓ Complete" and archived without a warning.
+ *
+ * Permissive on purpose, and safe to keep that way: any character class
+ * tightened here - the `\s` inside the brackets, which lets a tab or
+ * non-breaking space stand for an empty box - drops lines that used to count,
+ * and a task this parser drops is a task `openspec archive` stops warning about.
+ *
+ * Deliberately unanchored at the end: `.` does not match `\r`, so writing the
+ * description group as `(.*)$` would reject every line of a CRLF tasks.md.
+ */
+const TASK_LINE_PATTERN = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
+/**
+ * Parses every task line in a tasks file, in document order.
+ *
+ * Every line matching the pattern counts, wherever it sits - inside a code
+ * fence, an HTML comment or an indented block, as before. Skipping fenced
+ * checkboxes was tried and dropped: every rule for deciding which fence is
+ * "real" has an input where a stray or unbalanced ``` swallows genuine tasks.
+ * Counting a documented example as work is a loud, bypassable false positive;
+ * losing a real task is a silent one.
+ */
+export function parseTaskLines(content) {
+    const tasks = [];
+    for (const line of content.split('\n')) {
+        const match = line.match(TASK_LINE_PATTERN);
+        if (match) {
+            tasks.push({ done: match[1].toLowerCase() === 'x', description: match[2].trim() });
         }
     }
-    return { total, completed };
+    return tasks;
+}
+export function countTasksFromContent(content) {
+    const tasks = parseTaskLines(content);
+    return {
+        total: tasks.length,
+        completed: tasks.filter((task) => task.done).length,
+    };
 }
 /**
  * Identifies the change's tracked-tasks artifact: the artifact whose `generates`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

package/schemas/spec-driven/schema.yaml

@@ -13,8 +13,8 @@ artifacts:
       - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
       - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
       - **Capabilities**: Identify which specs will be created or modified:
-        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
-        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
       - **Impact**: Affected code, APIs, dependencies, or systems.
 
       IMPORTANT: The Capabilities section is critical. It creates the contract between
@@ -60,8 +60,10 @@ artifacts:
       visible behavior, it likely does not belong in the spec.
 
       Create one spec file per capability listed in the proposal's Capabilities section.
-      - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
-      - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
+      `<capability-path>` is the spec directory relative to `specs/` (for example,
+      `user-auth` or `identity/user-auth`). Preserve the full path:
+      - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
+      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
 
       There must be at least one spec file unless the change's `.openspec.yaml`
       sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
@@ -89,10 +91,10 @@ artifacts:
       by hand. Do NOT add `## Purpose` to a delta for an existing capability -
       that spec already has one and the delta's is ignored. To change an
       existing capability's Purpose - including a leftover `TBD` placeholder -
-      edit `openspec/specs/<capability>/spec.md` directly.
+      edit `openspec/specs/<capability-path>/spec.md` directly.
 
       MODIFIED requirements workflow:
-      1. Locate the existing requirement in openspec/specs/<capability>/spec.md
+      1. Locate the existing requirement in openspec/specs/<capability-path>/spec.md
       2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
       3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
       4. Ensure header text matches exactly (whitespace-insensitive)

package/schemas/spec-driven/templates/proposal.md

@@ -9,18 +9,20 @@
 ## Capabilities
 
 ### New Capabilities
-<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
-- `<name>`: <brief description of what this capability covers>
+<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
+     (e.g., user-auth or identity/user-auth) that follow the project's existing
+     spec organization. Each creates specs/<capability-path>/spec.md. -->
+- `<capability-path>`: <brief description of what this capability covers>
 
 ### Modified Capabilities
 <!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
      Only list here if spec-level behavior changes. Each needs a delta spec file.
-     Use existing spec names from openspec/specs/. Leave empty if no requirement
+     Use the exact existing path under openspec/specs/. Leave empty if no requirement
      changes. A change with no capabilities at all (pure refactor, tooling, docs)
      must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
      a zero-delta change without that marker. Do not invent a requirement just to
      satisfy validation. -->
-- `<existing-name>`: <what requirement is changing>
+- `<existing-capability-path>`: <what requirement is changing>
 
 ## Impact