@fission-ai/openspec 1.13.1 → 1.13.2

package/README.md

@@ -122,7 +122,7 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-**Requires Node.js 20.19.0 or higher.**
+**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.
 
 Install OpenSpec globally:
 
@@ -130,6 +130,12 @@ Install OpenSpec globally:
 npm install -g @fission-ai/openspec@latest
 ```
 
+Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:
+
+```bash
+brew install openspec
+```
+
 Then navigate to your project directory and initialize:
 
 ```bash
@@ -137,7 +143,7 @@ cd your-project
 openspec init
 ```
 
-> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
 Now talk to your AI:
 
@@ -151,7 +157,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
 >
-> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
+> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).
 
 ## Docs
 
@@ -208,6 +214,12 @@ AI coding assistants are powerful but unpredictable when requirements live only
 npm install -g @fission-ai/openspec@latest
 ```
 
+If you installed OpenSpec with Homebrew:
+
+```bash
+brew upgrade openspec
+```
+
 **Refresh agent instructions**
 
 Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:

package/dist/commands/workflow/instructions.js

@@ -7,7 +7,7 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputPath, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { isSpecsArtifactPath } from '../../core/artifact-graph/outputs.js';
 import { findUnreadDeltaFiles } from '../../utils/spec-discovery.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
@@ -394,15 +394,28 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             contextFiles[artifact.id] = outputs;
         }
     }
-    // Parse tasks if tracking file exists
+    // Parse every concrete file matched by apply.tracks. A tracking path may be
+    // a glob owned by an artifact with any ID, so treating it as one literal
+    // path loses task evidence for valid custom schemas.
     let parsedTasks = [];
+    const unavailableTrackingFiles = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
-        tracksFileExists = fs.existsSync(tracksPath);
-        if (tracksFileExists) {
-            const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            parsedTasks = parseTaskLines(tasksContent);
+        const tracksPaths = resolveArtifactOutputs(changeDir, tracksFile);
+        tracksFileExists = tracksPaths.length > 0;
+        for (const tracksPath of tracksPaths) {
+            try {
+                const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
+                parsedTasks.push(...parseTaskLines(tasksContent));
+            }
+            catch (error) {
+                const code = error?.code;
+                const message = error instanceof Error ? error.message : String(error);
+                unavailableTrackingFiles.push({
+                    path: tracksPath,
+                    reason: code && !message.includes(code) ? `${code}: ${message}` : message,
+                });
+            }
         }
     }
     const tasks = toTaskItems(parsedTasks);
@@ -435,6 +448,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             `The ${tracksFilename} file is missing and must be created.` +
                 `\n${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
+    else if (tracksFile && unavailableTrackingFiles.length > 0 && tasks.length === 0) {
+        state = 'blocked';
+        instruction = 'No readable task descriptions are available.';
+    }
     else if (tracksFile && tracksFileExists && tasks.length === 0) {
         // Tracking file exists but lists nothing an agent can work on: either no
         // checkboxes at all, or only checkboxes with no text after them.
@@ -444,7 +461,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             `The ${tracksFilename} file exists but contains no tasks to work on.` +
                 `\nAdd tasks to ${tracksFilename}, or rebuild it: ${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
-    else if (tracksFile && remaining === 0 && total > 0) {
+    else if (tracksFile &&
+        unavailableTrackingFiles.length === 0 &&
+        remaining === 0 &&
+        total > 0) {
         state = 'all_done';
         instruction = 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
     }
@@ -457,6 +477,12 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'ready';
         instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
     }
+    if (unavailableTrackingFiles.length > 0) {
+        const unavailableDetails = unavailableTrackingFiles
+            .map((file) => `- ${file.path}: ${file.reason}`)
+            .join('\n');
+        instruction += `\nTask completion is not verified because tracking evidence was unavailable:\n${unavailableDetails}`;
+    }
     const warnings = await collectApplyWarnings({
         state,
         schema,
@@ -471,6 +497,8 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
+        taskTrackingConfigured: tracksFile !== null,
+        ...(unavailableTrackingFiles.length > 0 ? { unavailableTrackingFiles } : {}),
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         ...(missingPrerequisites.length > 0 ? { missingPrerequisites } : {}),

package/dist/commands/workflow/shared.d.ts

@@ -28,6 +28,11 @@ export interface ApplyInstructions {
         remaining: number;
     };
     tasks: TaskItem[];
+    taskTrackingConfigured: boolean;
+    unavailableTrackingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
     state: 'blocked' | 'all_done' | 'ready';
     missingArtifacts?: string[];
     /**

package/dist/core/archive.js

@@ -7,7 +7,7 @@ import { Validator } from './validation/validator.js';
 import { VALIDATION_MESSAGES } from './validation/constants.js';
 import chalk from 'chalk';
 import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from './root-selection.js';
-import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, retireSpec, finalizeRetiredSpec, } from './specs-apply.js';
+import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, retireSpec, finalizeRetiredSpec, pruneEmptyDirs, } from './specs-apply.js';
 import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../utils/spec-discovery.js';
 import { METADATA_FILENAME, readRetireCapabilitiesMarker, readSkipSpecsMarker } from '../utils/change-metadata.js';
 import { confirmPrompt, isNonInteractivePromptError } from '../utils/interactive.js';
@@ -289,6 +289,14 @@ async function copyDirContents(src, dest) {
     }
     await fs.chmod(dest, sourceStat.mode & 0o7777);
 }
+/** SHA-256 of one file's bytes, streamed so a large file is never held whole. */
+async function fingerprintFileContents(filePath) {
+    const fileHash = createHash('sha256');
+    for await (const chunk of createReadStream(filePath)) {
+        fileHash.update(chunk);
+    }
+    return fileHash.digest();
+}
 async function fingerprintDirectoryContents(root) {
     const hash = createHash('sha256');
     const updateHashField = (label, value) => {
@@ -301,13 +309,7 @@ async function fingerprintDirectoryContents(root) {
         hash.update(labelBuffer);
         hash.update(valueBuffer);
     };
-    const fingerprintFile = async (filePath) => {
-        const fileHash = createHash('sha256');
-        for await (const chunk of createReadStream(filePath)) {
-            fileHash.update(chunk);
-        }
-        return fileHash.digest();
-    };
+    const fingerprintFile = fingerprintFileContents;
     const visit = async (dir, relativeDir) => {
         const before = await fs.lstat(dir, { bigint: true });
         if (!before.isDirectory()) {
@@ -367,15 +369,198 @@ async function assertCopiedDirectoryUnchanged(stagedSource, destination, expecte
 }
 /**
  * Move a directory from src to dest. On Windows, fs.rename() can fail with
- * EPERM, and cross-device moves fail with EXDEV. When the source can first be
- * renamed to a private sibling, fall back to a verified copy-then-remove. A
- * source that cannot be staged is left untouched rather than copied and deleted
- * through a path another process may still be editing.
+ * EPERM, and cross-device moves fail with EXDEV. Prefer renaming the source
+ * to a private sibling first, then copy-then-remove. When that staging rename
+ * also fails with EPERM/EXDEV — the usual Windows case for a directory that
+ * still has children, because a watcher holds a directory-enumeration handle —
+ * copy from the original source instead. Fingerprints still abort if the tree
+ * changes mid-copy. A staging failure that is not EPERM/EXDEV still leaves
+ * the source untouched rather than copying through a path we could not claim.
  */
 class MoveDestinationRetainedError extends Error {
 }
 class RetirementBackupsRetainedError extends Error {
 }
+function isFallbackRenameCode(code) {
+    return code === 'EPERM' || code === 'EXDEV';
+}
+/**
+ * Every entry under `root`, deepest first, as paths relative to it.
+ *
+ * The listing is what bounds the removal below. Anything that appears after it
+ * is simply not in the set, so it cannot be deleted by the cleanup.
+ */
+async function listTreeEntriesDeepestFirst(root) {
+    const entries = [];
+    const visit = async (dir, relativeDir) => {
+        for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+            const relative = relativeDir === '' ? entry.name : path.join(relativeDir, entry.name);
+            if (entry.isDirectory()) {
+                await visit(path.join(dir, entry.name), relative);
+                entries.push({ relative, kind: 'directory' });
+            }
+            else {
+                // A symlink to a directory is not a directory here, and its content is
+                // its target, not bytes to read - reading one raises EISDIR. Record the
+                // kind so cleanup compares each entry the way the copy wrote it.
+                entries.push({ relative, kind: entry.isSymbolicLink() ? 'symlink' : 'file' });
+            }
+        }
+    };
+    await visit(root, '');
+    return entries;
+}
+/**
+ * Remove exactly the entries that were copied and verified, deepest first.
+ *
+ * The move is only safe to finish by deleting the source, and the source of the
+ * unstaged fallback is still the live change directory: the archive claim
+ * covers the destination, not it. A recursive remove would delete whatever is
+ * there at that moment, including a file a concurrent writer added after the
+ * final fingerprint - data that never reached the destination.
+ *
+ * Removing a named set instead means a late arrival is never in it. It is left
+ * on disk, and the `rmdir` of its parent fails with ENOTEMPTY, which the caller
+ * reports as a retained destination. The move does not complete silently.
+ *
+ * `entries` must be listed before the final fingerprint, so that an arrival is
+ * either caught by that fingerprint or absent from the set.
+ *
+ * An edit to a file that is already in the set is covered by claiming each file
+ * before reading it: `rename` is atomic, so once a file is under its claim name
+ * the bytes there are ours. A writer that rewrites the file by path after that
+ * point creates a new file at the original path, which is not in `entries`, is
+ * never deleted, and makes the parent `rmdir` fail with ENOTEMPTY - reported as
+ * a retained destination. A writer that got there first is caught by comparing
+ * the claimed bytes against the copy: on a mismatch the file is put back and
+ * the move is abandoned with both trees intact, because the destination holds
+ * the older content and deleting the source would lose the newer.
+ *
+ * What remains outside this, as for any copy, is a writer holding an open
+ * descriptor that writes through it after the comparison. Staging is still
+ * preferred whenever the rename is permitted at all.
+ */
+/**
+ * A claim suffix no entry in this move can already carry.
+ *
+ * A fixed suffix collides with a source file that legitimately ends in it:
+ * claiming `x` would rename it over a real `x.openspec-claim`, and that file's
+ * own turn would then fail with ENOENT after part of the live source had
+ * already been removed. So draw a fresh suffix per move and prove it against
+ * the very set being removed - if no entry ends with the suffix, no claim of
+ * one entry can land on another.
+ */
+function makeClaimSuffix(entries) {
+    const names = entries.map((entry) => entry.relative);
+    for (;;) {
+        const suffix = `.openspec-claim-${randomUUID()}`;
+        if (!names.some((name) => name.endsWith(suffix)))
+            return suffix;
+    }
+}
+/** What the entry holds now, for comparison against the copy. */
+async function readEntryIdentity(entryPath, kind) {
+    return kind === 'symlink'
+        ? `symlink:${await fs.readlink(entryPath)}`
+        : `file:${(await fingerprintFileContents(entryPath)).toString('hex')}`;
+}
+async function removeVerifiedTree(root, entries, destination) {
+    const claimSuffix = makeClaimSuffix(entries);
+    for (const entry of entries) {
+        const target = path.join(root, entry.relative);
+        if (entry.kind === 'directory') {
+            await fs.rmdir(target);
+            continue;
+        }
+        const claimed = target + claimSuffix;
+        await fs.rename(target, claimed);
+        let claimedIdentity;
+        let copiedIdentity;
+        try {
+            claimedIdentity = await readEntryIdentity(claimed, entry.kind);
+            copiedIdentity = await readEntryIdentity(path.join(destination, entry.relative), entry.kind);
+        }
+        catch (error) {
+            await fs.rename(claimed, target).catch(() => undefined);
+            throw error;
+        }
+        if (claimedIdentity !== copiedIdentity) {
+            await fs.rename(claimed, target).catch(() => undefined);
+            throw new Error(`${target} changed after it was verified, so the copy at ${destination} ` +
+                'does not hold its current content.');
+        }
+        await fs.rm(claimed, { force: true });
+    }
+    await fs.rmdir(root);
+}
+async function copyThenRemoveDirectory(source, dest, options, restoreSource) {
+    let destIsOurs = false;
+    let sourceFingerprint;
+    try {
+        sourceFingerprint = await fingerprintDirectoryContents(source);
+        await fs.mkdir(dest, { mode: 0o700 });
+        destIsOurs = true;
+        await copyDirContents(source, dest);
+        await options.verifyCopiedDestination?.(source);
+        await assertCopiedDirectoryUnchanged(source, dest, sourceFingerprint);
+    }
+    catch (copyError) {
+        if (destIsOurs) {
+            await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+        }
+        if (restoreSource) {
+            try {
+                await restoreSource();
+            }
+            catch (restoreError) {
+                throw new Error(`${copyError instanceof Error ? copyError.message : String(copyError)} ` +
+                    `Could not restore the staged source at ${source} ` +
+                    `(${restoreError instanceof Error ? restoreError.message : String(restoreError)}).`);
+            }
+        }
+        if (copyError.code === 'EEXIST') {
+            throw new ArchiveBlockedError('archive_target_exists', `Archive '${path.basename(dest)}' already exists.`);
+        }
+        throw copyError;
+    }
+    let verifiedEntries;
+    try {
+        // Listed before the verification, not after it. A file that arrives before
+        // the fingerprint changes it and aborts the move; one that arrives after is
+        // not in this set. Listing afterwards would leave a window in which an
+        // arrival is both unverified and deletable.
+        verifiedEntries = await listTreeEntriesDeepestFirst(source);
+        await options.verifyCopiedDestination?.(source);
+        await assertCopiedDirectoryUnchanged(source, dest, sourceFingerprint);
+    }
+    catch (verificationError) {
+        await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+        if (restoreSource) {
+            try {
+                await restoreSource();
+            }
+            catch (restoreError) {
+                throw new Error(`${verificationError instanceof Error ? verificationError.message : String(verificationError)} ` +
+                    `Could not restore the staged source at ${source} ` +
+                    `(${restoreError instanceof Error ? restoreError.message : String(restoreError)}).`);
+            }
+        }
+        throw verificationError;
+    }
+    try {
+        await removeVerifiedTree(source, verifiedEntries, dest);
+    }
+    catch (cleanupError) {
+        // Removal may already have deleted part of the source, or stopped on an
+        // entry that appeared after verification. The destination is now the only
+        // complete copy, so never erase it while trying to make this failed move
+        // look atomic.
+        throw new MoveDestinationRetainedError(`Copied ${source} to ${dest}, but could not remove the source at ` +
+            `${source} completely ` +
+            `(${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}). ` +
+            'The complete destination was retained for recovery.');
+    }
+}
 async function moveDirectory(src, dest, options = {}) {
     try {
         await fs.rename(src, dest);
@@ -387,71 +572,24 @@ async function moveDirectory(src, dest, options = {}) {
         if (code === 'ENOTEMPTY' || code === 'EEXIST') {
             throw new ArchiveBlockedError('archive_target_exists', `Archive '${path.basename(dest)}' already exists.`);
         }
-        if (code === 'EPERM' || code === 'EXDEV') {
+        if (isFallbackRenameCode(code)) {
             const stagedSource = path.join(path.dirname(src), `.openspec-move-${randomUUID()}`);
             try {
                 await fs.rename(src, stagedSource);
             }
             catch (stageError) {
+                const stageCode = stageError?.code;
+                if (isFallbackRenameCode(stageCode)) {
+                    await copyThenRemoveDirectory(src, dest, options);
+                    return;
+                }
                 throw new Error(`Could not safely stage ${src} before the fallback archive copy ` +
                     `(${stageError instanceof Error ? stageError.message : String(stageError)}). ` +
                     'No fallback copy was attempted.');
             }
-            let destIsOurs = false;
-            let stagedFingerprint;
-            try {
-                stagedFingerprint = await fingerprintDirectoryContents(stagedSource);
-                await fs.mkdir(dest, { mode: 0o700 });
-                destIsOurs = true;
-                await copyDirContents(stagedSource, dest);
-                await options.verifyCopiedDestination?.(stagedSource);
-                await assertCopiedDirectoryUnchanged(stagedSource, dest, stagedFingerprint);
-            }
-            catch (copyError) {
-                if (destIsOurs) {
-                    await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
-                }
-                try {
-                    await fs.rename(stagedSource, src);
-                }
-                catch (restoreError) {
-                    throw new Error(`${copyError instanceof Error ? copyError.message : String(copyError)} ` +
-                        `Could not restore the staged source at ${stagedSource} ` +
-                        `(${restoreError instanceof Error ? restoreError.message : String(restoreError)}).`);
-                }
-                if (copyError.code === 'EEXIST') {
-                    throw new ArchiveBlockedError('archive_target_exists', `Archive '${path.basename(dest)}' already exists.`);
-                }
-                throw copyError;
-            }
-            try {
-                await options.verifyCopiedDestination?.(stagedSource);
-                await assertCopiedDirectoryUnchanged(stagedSource, dest, stagedFingerprint);
-            }
-            catch (verificationError) {
-                await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
-                try {
-                    await fs.rename(stagedSource, src);
-                }
-                catch (restoreError) {
-                    throw new Error(`${verificationError instanceof Error ? verificationError.message : String(verificationError)} ` +
-                        `Could not restore the staged source at ${stagedSource} ` +
-                        `(${restoreError instanceof Error ? restoreError.message : String(restoreError)}).`);
-                }
-                throw verificationError;
-            }
-            try {
-                await fs.rm(stagedSource, { recursive: true, force: true });
-            }
-            catch (cleanupError) {
-                // Recursive removal may already have deleted part of the source. The
-                // destination is now the only complete copy, so never erase it while
-                // trying to make this failed move look atomic.
-                throw new MoveDestinationRetainedError(`Copied ${src} to ${dest}, but could not remove the staged source at ` +
-                    `${stagedSource} completely ` +
-                    `(${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}). ` +
-                    'The complete destination was retained for recovery.');
-            }
+            await copyThenRemoveDirectory(stagedSource, dest, options, async () => {
+                await fs.rename(stagedSource, src);
+            });
         }
         else {
             throw err;
@@ -473,6 +611,10 @@ async function assertArchiveDestinationAvailable(archivePath, archiveName) {
 function archiveClaimPath(archivePath, _archiveName) {
     return path.join(path.dirname(archivePath), '.openspec-archive.lock');
 }
+function isSameArchiveClaimFile(first, second) {
+    return (first.ino === second.ino &&
+        (first.dev === second.dev || first.dev === 0n || second.dev === 0n));
+}
 async function releaseArchiveClaim(claim, claimPath) {
     const owned = await claim.handle.stat({ bigint: true }).catch(() => undefined);
     await claim.handle.close().catch(() => undefined);
@@ -485,10 +627,8 @@ async function releaseArchiveClaim(claim, claimPath) {
         const current = await fs.lstat(claimPath, { bigint: true });
         const contents = await fs.readFile(claimPath, 'utf8');
         const currentAfterRead = await fs.lstat(claimPath, { bigint: true });
-        if (current.dev === owned.dev &&
-            current.ino === owned.ino &&
-            current.dev === currentAfterRead.dev &&
-            current.ino === currentAfterRead.ino &&
+        if (isSameArchiveClaimFile(current, owned) &&
+            isSameArchiveClaimFile(current, currentAfterRead) &&
             contents === claim.contents) {
             await fs.unlink(claimPath);
         }
@@ -666,7 +806,29 @@ async function assertDistinctMutationTargets(mutations) {
         owners.set(identity, mutation.update.id);
     }
 }
-async function captureSpecSnapshots(mutations) {
+/**
+ * The deepest directory at or above `dir` that exists, never going above
+ * `boundaryDir`. Used as the floor for a rollback prune: everything below it
+ * was created by the write being undone, and it was not.
+ */
+async function deepestExistingAncestor(dir, boundaryDir) {
+    let current = dir;
+    for (;;) {
+        if (current === boundaryDir || !current.startsWith(boundaryDir + path.sep)) {
+            return boundaryDir;
+        }
+        try {
+            await fs.lstat(current);
+            return current;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        current = path.dirname(current);
+    }
+}
+async function captureSpecSnapshots(mutations, mainSpecsDir) {
     return Promise.all(mutations.map(async ({ update, outcome, rebuilt }) => {
         try {
             const stat = await fs.lstat(update.target);
@@ -714,6 +876,7 @@ async function captureSpecSnapshots(mutations) {
                     target: update.target,
                     existed: false,
                     outcome,
+                    pruneBoundary: await deepestExistingAncestor(path.dirname(update.target), mainSpecsDir),
                     ...(outcome === 'write' ? { expectedContent: Buffer.from(rebuilt) } : {}),
                 };
             }
@@ -721,7 +884,7 @@ async function captureSpecSnapshots(mutations) {
         }
     }));
 }
-async function restoreSpecSnapshots(snapshots) {
+async function restoreSpecSnapshots(snapshots, mainSpecsDir) {
     const errors = [];
     for (const snapshot of [...snapshots].reverse()) {
         try {
@@ -799,6 +962,10 @@ async function restoreSpecSnapshots(snapshots) {
             }
             if (!snapshot.existed) {
                 await fs.rm(snapshot.target, { force: true });
+                // Only a capability directory this write created is ours to take back.
+                // One the user already had stays, empty or not, with its own mode -
+                // pruneEmptyDirs never removes its boundary.
+                await pruneEmptyDirs(path.dirname(snapshot.target), snapshot.pruneBoundary ?? mainSpecsDir);
                 continue;
             }
             if (snapshot.symlink !== undefined) {
@@ -1406,7 +1573,7 @@ export class ArchiveCommand {
                                     'No files were changed; review the new content and rerun.');
                             }
                         }
-                        const specSnapshots = await captureSpecSnapshots(mutations);
+                        const specSnapshots = await captureSpecSnapshots(mutations, mainSpecsDir);
                         const specSnapshotsByTarget = new Map(specSnapshots.map((snapshot) => [snapshot.target, snapshot]));
                         const mutationAttempts = new Set();
                         try {
@@ -1611,7 +1778,7 @@ export class ArchiveCommand {
                                 throw error;
                             const rollbackErrors = [];
                             try {
-                                await restoreSpecSnapshots(specSnapshots.filter(({ target }) => mutationAttempts.has(target)));
+                                await restoreSpecSnapshots(specSnapshots.filter(({ target }) => mutationAttempts.has(target)), mainSpecsDir);
                             }
                             catch (rollbackError) {
                                 rollbackErrors.push(rollbackError instanceof Error

package/dist/core/artifact-graph/outputs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Checks if a path contains glob pattern characters.
+ * Recognizes artifact globs while preserving literal output filenames.
  */
 export declare function isGlobPattern(pattern: string): boolean;
 /**

package/dist/core/artifact-graph/outputs.js

@@ -2,11 +2,31 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import fg from 'fast-glob';
 import { FileSystemUtils } from '../../utils/file-system.js';
+const EXTGLOB_RE = /[!*+?@]\([^(]*\)/u;
+const BRACE_EXPANSION_SEPARATORS_RE = /,|\.\./u;
+function hasBraceExpansion(pattern) {
+    const openings = [];
+    for (let index = 0; index < pattern.length; index += 1) {
+        if (pattern[index] === '{')
+            openings.push(index);
+        if (pattern[index] !== '}')
+            continue;
+        const opening = openings.pop();
+        if (opening !== undefined && BRACE_EXPANSION_SEPARATORS_RE.test(pattern.slice(opening, index))) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
- * Checks if a path contains glob pattern characters.
+ * Recognizes artifact globs while preserving literal output filenames.
  */
 export function isGlobPattern(pattern) {
-    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+    // Keep the original wildcard rules and recognize brace expansions and extglobs.
+    // Its full dynamic predicate also reinterprets literal !, parentheses, and backslashes.
+    const normalized = FileSystemUtils.toPosixPath(pattern);
+    return normalized.includes('*') || normalized.includes('?') || normalized.includes('[')
+        || EXTGLOB_RE.test(normalized) || hasBraceExpansion(normalized);
 }
 /**
  * Returns whether an artifact generates files under the change's specs/ tree.
@@ -82,16 +102,26 @@ export function resolveArtifactOutputs(changeDir, generates) {
         }
     }
     const normalizedPattern = FileSystemUtils.toPosixPath(generates);
-    assertGlobDirectoryTraversal(changeDir, changeDir, normalizedPattern.split('/').slice(0, -1));
-    const matches = fg
-        .sync(normalizedPattern, {
+    const globOptions = {
         cwd: changeDir,
         onlyFiles: true,
         absolute: true,
-        // Preserve existing support for linked artifact directories. Every
-        // concrete match is canonically confined below before it is returned.
+        // Preserve linked artifact directories; confine traversal and concrete matches.
         followSymbolicLinks: true,
-    })
+    };
+    // Task generation expands braces without accessing the filesystem. Validate
+    // every task base before globbing, including paths introduced by expansion.
+    const tasks = fg.generateTasks(normalizedPattern, globOptions);
+    for (const task of tasks) {
+        FileSystemUtils.assertPathWithin(changeDir, path.resolve(changeDir, task.base));
+    }
+    for (const task of tasks) {
+        for (const positivePattern of task.positive) {
+            assertGlobDirectoryTraversal(changeDir, changeDir, positivePattern.split('/').slice(0, -1));
+        }
+    }
+    const matches = fg
+        .sync(normalizedPattern, globOptions)
         .map((match) => {
         const normalizedMatch = path.normalize(match);
         FileSystemUtils.assertPathWithin(changeDir, normalizedMatch);

package/dist/core/command-generation/adapters/continue.js

@@ -16,12 +16,16 @@ export const continueAdapter = {
         return path.join('.continue', 'prompts', `opsx-${commandId}.prompt`);
     },
     formatFile(content) {
+        // Continue injects an invoked prompt into the model context. Smaller local
+        // models can otherwise mistake the workflow name for a tool to call (#925).
         return `---
 name: ${escapeYamlValue(`opsx-${content.id}`)}
 description: ${escapeYamlValue(content.description)}
 invokable: true
 ---
 
+This workflow prompt is already active. Follow its instructions directly. Do not call a tool named after this workflow.
+
 ${content.body}
 `;
     },