@fission-ai/openspec 1.13.0 → 1.13.2

package/dist/core/archive.js

@@ -7,12 +7,13 @@ 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 { discoverSpecFiles, hasAnyFileUnder } from '../utils/spec-discovery.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';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { folderStyleNameProblem } from './id.js';
+import { describeNestedChange, findNestedChangesIn, } from '../utils/nested-change.js';
 function isMissingPathError(error) {
     return (typeof error === 'object' &&
         error !== null &&
@@ -288,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) => {
@@ -300,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()) {
@@ -366,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);
@@ -386,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;
@@ -472,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);
@@ -484,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);
         }
@@ -665,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);
@@ -713,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) } : {}),
                 };
             }
@@ -720,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 {
@@ -798,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) {
@@ -949,6 +1117,14 @@ export class ArchiveCommand {
                 ? `Change '${changeName}' not found. Available changes: ${available.join(', ')}`
                 : `Change '${changeName}' not found. No active changes exist in this root.`);
         }
+        // Archiving a namespace folder moves an active, unfinished change into the
+        // archive under a name nobody will look for, and never applies its deltas.
+        // That is silent data loss, so it is refused outright rather than warned
+        // about (#1846).
+        const nested = await findNestedChangesIn(changesDir, changeName);
+        if (nested) {
+            throw new ArchiveBlockedError('archive_change_is_namespace_folder', `Cannot archive '${changeName}': ${describeNestedChange(nested)}`, `Rename openspec/changes/${nested.nested[0]}/ to a flat change directory, then archive it.`);
+        }
         const skipValidation = options.validate === false || options.noValidate === true;
         // Validate specs and change before archiving
         if (!skipValidation) {
@@ -993,6 +1169,13 @@ export class ArchiveCommand {
             // folder, so only a regular file counts.
             const rootSpecStat = await fs.stat(path.join(changeSpecsDir, 'spec.md')).catch(() => null);
             let hasDeltaSpecs = rootSpecStat?.isFile() === true;
+            // Likewise for delta sections in any other file the merge path does not
+            // read (specs/<capability>.md, a note beside spec.md): without this the
+            // zero-delta leniency below archives the change as done with nothing
+            // merged, although validate rejects it.
+            if (!hasDeltaSpecs) {
+                hasDeltaSpecs = (await findUnreadDeltaFiles(changeSpecsDir)).length > 0;
+            }
             // A change that declares skip_specs must not carry any file under
             // specs/ — validate reports that as a conflict, so archive has to run
             // the same check instead of skipping validation because the files
@@ -1390,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 {
@@ -1595,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/artifact-graph/schema.d.ts

@@ -10,4 +10,18 @@ export declare function loadSchema(filePath: string): SchemaYaml;
  * Parses and validates an artifact schema from YAML content.
  */
 export declare function parseSchema(yamlContent: string): SchemaYaml;
+/**
+ * Describes an `apply.tracks` value that is not exactly equal to any artifact's
+ * `generates` value, or returns undefined when there is nothing to report.
+ *
+ * The tracked-tasks lookups select the artifact whose `generates` string equals
+ * `tracks`, so this is a progress-discovery problem, not a claim that nothing
+ * produces the file: a glob `generates: tasks/*.md` really does generate
+ * `tracks: tasks/main.md`, yet the strings differ, so the lookup still misses.
+ * Either way apply keeps working (it reads the path directly), but `openspec
+ * list` and `openspec status` fall back to counting the top-level `tasks.md`,
+ * and apply's remedy cannot name an artifact to build. A typo such as
+ * `task.md` is the other usual cause.
+ */
+export declare function findApplyTracksWarning(schema: SchemaYaml): string | undefined;
 //# sourceMappingURL=schema.d.ts.map

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

@@ -30,6 +30,8 @@ export function parseSchema(yamlContent) {
     validateNoDuplicateIds(schema.artifacts);
     // Check that all requires references are valid
     validateRequiresReferences(schema.artifacts);
+    // Check that the apply phase names artifacts this schema declares
+    validateApplyReferences(schema);
     // Check for cycles
     validateNoCycles(schema.artifacts);
     return schema;
@@ -59,6 +61,56 @@ function validateRequiresReferences(artifacts) {
         }
     }
 }
+/**
+ * Validates that every `apply.requires` id is an artifact the schema declares.
+ *
+ * Apply skips an id that no artifact declares, so a typo silently dropped that
+ * artifact from the apply gate. An unknown artifact `requires` is already a
+ * load error, and this is the same kind of reference.
+ *
+ * `apply.tracks` is deliberately not checked here. It is a path, not an id:
+ * apply reads it as written, so a schema whose `tracks` value does not exactly
+ * match any `generates` value (a hand-written `TODO.md`, or `tasks/main.md`
+ * under a glob `generates: tasks/*.md` that really does produce it) works
+ * today, and failing the load would break every command on it.
+ * `openspec schema validate` reports that case as a warning instead
+ * (see `findApplyTracksWarning`).
+ */
+function validateApplyReferences(schema) {
+    const apply = schema.apply;
+    if (!apply)
+        return;
+    const validIds = schema.artifacts.map(a => a.id);
+    for (const req of apply.requires) {
+        if (!validIds.includes(req)) {
+            throw new SchemaValidationError(`Invalid apply.requires reference: '${req}' does not exist (artifacts: ${validIds.join(', ')})`);
+        }
+    }
+}
+/**
+ * Describes an `apply.tracks` value that is not exactly equal to any artifact's
+ * `generates` value, or returns undefined when there is nothing to report.
+ *
+ * The tracked-tasks lookups select the artifact whose `generates` string equals
+ * `tracks`, so this is a progress-discovery problem, not a claim that nothing
+ * produces the file: a glob `generates: tasks/*.md` really does generate
+ * `tracks: tasks/main.md`, yet the strings differ, so the lookup still misses.
+ * Either way apply keeps working (it reads the path directly), but `openspec
+ * list` and `openspec status` fall back to counting the top-level `tasks.md`,
+ * and apply's remedy cannot name an artifact to build. A typo such as
+ * `task.md` is the other usual cause.
+ */
+export function findApplyTracksWarning(schema) {
+    const tracks = schema.apply?.tracks;
+    if (tracks == null || schema.artifacts.some(a => a.generates === tracks))
+        return undefined;
+    return (`apply.tracks '${tracks}' does not exactly match any artifact's generates value ` +
+        `(generates: ${schema.artifacts.map(a => a.generates).join(', ')}), ` +
+        `so OpenSpec cannot tell which artifact's progress it tracks. ` +
+        `Apply still reads that file as written, but list and status count tasks.md instead. ` +
+        `Make apply.tracks exactly equal one of those generates values, ` +
+        `or confirm that file is maintained outside the artifact graph.`);
+}
 /**
  * Validates that there are no cyclic dependencies.
  * Uses DFS to detect cycles and reports the full cycle path.

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

@@ -18,6 +18,9 @@ function relativePathSchema(fieldName) {
     });
 }
 // Artifact definition schema
+// Upper bound on artifacts in one schema. Keeps `validateNoCycles`' recursive
+// DFS well inside the stack limit for any accepted input.
+const MAX_ARTIFACTS = 1000;
 export const ArtifactSchema = z.object({
     id: z.string().min(1, { error: 'Artifact ID is required' }),
     generates: relativePathSchema('generates field'),
@@ -40,7 +43,15 @@ export const SchemaYamlSchema = z.object({
     name: z.string().min(1, { error: 'Schema name is required' }),
     version: z.number().int().positive({ error: 'Version must be a positive integer' }),
     description: z.string().optional(),
-    artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+    artifacts: z
+        .array(ArtifactSchema)
+        .min(1, { error: 'At least one artifact required' })
+        // Bounded so a hostile schema cannot drive the cycle-detection DFS past the
+        // V8 stack limit and crash with an uncaught RangeError instead of a
+        // validation error.
+        .max(MAX_ARTIFACTS, {
+        error: `A schema may declare at most ${MAX_ARTIFACTS} artifacts`,
+    }),
     // Optional apply phase configuration (for schema-aware apply instructions)
     apply: ApplyPhaseSchema.optional(),
 });

package/dist/core/change-status-policy.d.ts

@@ -33,5 +33,19 @@ export interface ActionContextInput {
 }
 export declare function summarizePlanningHome(planningHome: PlanningHome | undefined): PlanningHomeSummary | undefined;
 export declare function buildActionContext(input: ActionContextInput): ActionContext;
+/**
+ * The one next action for a change, in both the forms the CLI needs.
+ *
+ * `sentence` is what the JSON `nextSteps` contract publishes; `command` is the
+ * bare command the text surface prints. Both are built here so the two
+ * surfaces can never name a different next step.
+ */
+export interface ChangeNextStep {
+    /** Ready-to-run command, including any `--store` flag. */
+    command: string;
+    /** Sentence form carried by the JSON `nextSteps` array. */
+    sentence: string;
+}
+export declare function resolveNextStep(input: ChangeNextStepsInput): ChangeNextStep | undefined;
 export declare function buildNextSteps(input: ChangeNextStepsInput): string[];
 //# sourceMappingURL=change-status-policy.d.ts.map