@fission-ai/openspec 1.13.1 → 1.14.0

package/dist/core/archive.js

@@ -7,9 +7,9 @@ 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 { METADATA_FILENAME, formatUnknownChangeMetadataKeysMessage, readRetireCapabilitiesMarker, readSkipSpecsMarker, readUnknownChangeMetadataKeys, } from '../utils/change-metadata.js';
 import { confirmPrompt, isNonInteractivePromptError } from '../utils/interactive.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { folderStyleNameProblem } from './id.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) {
@@ -958,6 +1125,13 @@ export class ArchiveCommand {
         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 unknownMetadataKeys = readUnknownChangeMetadataKeys(changeDir);
+        const unknownMetadataWarning = unknownMetadataKeys.length > 0
+            ? formatUnknownChangeMetadataKeysMessage(unknownMetadataKeys)
+            : undefined;
+        if (unknownMetadataWarning && !json) {
+            console.warn(chalk.yellow(unknownMetadataWarning));
+        }
         const skipValidation = options.validate === false || options.noValidate === true;
         // Validate specs and change before archiving
         if (!skipValidation) {
@@ -1406,7 +1580,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 +1785,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
@@ -1660,7 +1834,13 @@ export class ArchiveCommand {
                 path: archivePath,
                 specsUpdated,
                 ...(totals ? { totals } : {}),
-                ...(specWarnings.length > 0 ? { warnings: specWarnings } : {}),
+                ...(specWarnings.length > 0 || unknownMetadataWarning
+                    ? {
+                        warnings: unknownMetadataWarning
+                            ? [...specWarnings, unknownMetadataWarning]
+                            : specWarnings,
+                    }
+                    : {}),
             };
         }
         finally {

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -32,6 +32,8 @@ export interface ChangeContext {
     planningHome?: PlanningHome;
     /** Parsed change metadata, when present */
     metadata?: ChangeMetadata;
+    /** Non-fatal metadata diagnostics for text and JSON command surfaces */
+    warnings?: string[];
     /**
      * Artifact IDs counted as complete only because the change declares
      * skip_specs, not because their files exist. Kept separate so status can
@@ -85,6 +87,8 @@ export interface ArtifactInstructions {
     skipped?: boolean;
     /** Present only when skipped: tells the consumer not to create the artifact */
     warning?: string;
+    /** Non-fatal metadata diagnostics */
+    warnings?: string[];
 }
 /**
  * Warning attached to instructions for an artifact skipped via skip_specs.
@@ -152,6 +156,8 @@ export interface ChangeStatus {
     applyRequires: string[];
     /** Status of each artifact */
     artifacts: ArtifactStatus[];
+    /** Non-fatal metadata diagnostics */
+    warnings?: string[];
 }
 export interface ArtifactPathSummary {
     outputPath: string;
@@ -211,5 +217,6 @@ export declare function generateInstructions(context: ChangeContext, artifactId:
  */
 export declare function formatChangeStatus(context: ChangeContext, options?: {
     storeId?: string;
+    implementationRoot?: string;
 }): ChangeStatus;
 //# sourceMappingURL=instruction-loader.d.ts.map

package/dist/core/artifact-graph/instruction-loader.js

@@ -4,7 +4,7 @@ import { getSchemaDir, resolveSchema, listSchemasWithInfo } from './resolver.js'
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
 import { isSpecsArtifactPath, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
-import { readChangeMetadata, resolveSchemaForChange } from '../../utils/change-metadata.js';
+import { formatUnknownChangeMetadataKeysMessage, readChangeMetadata, readUnknownChangeMetadataKeys, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { buildActionContext, buildNextSteps, summarizePlanningHome, } from '../change-status-policy.js';
 import { readProjectConfig, validateConfigRules } from '../project-config.js';
@@ -78,6 +78,10 @@ export function loadTemplate(schemaName, templatePath, projectRoot) {
 export function loadChangeContext(projectRoot, changeName, schemaName, options = {}) {
     const changeDir = FileSystemUtils.canonicalizeExistingPath(options.changeDir ?? path.join(projectRoot, 'openspec', 'changes', changeName));
     const metadata = readChangeMetadata(changeDir, projectRoot) ?? undefined;
+    const unknownMetadataKeys = readUnknownChangeMetadataKeys(changeDir);
+    const warnings = unknownMetadataKeys.length > 0
+        ? [formatUnknownChangeMetadataKeysMessage(unknownMetadataKeys)]
+        : [];
     const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName, projectRoot, {
         metadata: metadata ?? null,
         projectConfig: options.projectConfig,
@@ -107,6 +111,7 @@ export function loadChangeContext(projectRoot, changeName, schemaName, options =
         projectRoot,
         ...(options.planningHome ? { planningHome: options.planningHome } : {}),
         ...(metadata ? { metadata } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
         ...(skippedArtifacts.size > 0 ? { skippedArtifacts } : {}),
     };
 }
@@ -164,6 +169,7 @@ export function generateInstructions(context, artifactId, projectRoot, options =
         context: configContext,
         rules: configRules,
         ...(options.references !== undefined ? { references: options.references } : {}),
+        ...(context.warnings ? { warnings: context.warnings } : {}),
         ...(context.skippedArtifacts?.has(artifact.id)
             ? { skipped: true, warning: SKIP_SPECS_INSTRUCTIONS_WARNING }
             : {}),
@@ -279,8 +285,19 @@ export function formatChangeStatus(context, options = {}) {
         actionContext: buildActionContext({
             projectRoot: context.projectRoot,
             artifactIds,
+            ...(options.storeId
+                ? {
+                    store: {
+                        id: options.storeId,
+                        ...(options.implementationRoot
+                            ? { implementationRoot: options.implementationRoot }
+                            : {}),
+                    },
+                }
+                : {}),
         }),
         artifacts: artifactStatuses,
+        ...(context.warnings ? { warnings: context.warnings } : {}),
     };
 }
 //# sourceMappingURL=instruction-loader.js.map

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/change-metadata/schema.d.ts

@@ -5,6 +5,9 @@ export declare const InitiativeLinkSchema: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strict>;
 export type InitiativeLink = z.infer<typeof InitiativeLinkSchema>;
+/** Top-level keys ChangeMetadataSchema recognizes. Anything else is ignored. */
+export declare const CHANGE_METADATA_KNOWN_KEYS: readonly ["schema", "created", "goal", "affected_areas", "initiative", "skip_specs", "retire_capabilities"];
+export type ChangeMetadataKnownKey = (typeof CHANGE_METADATA_KNOWN_KEYS)[number];
 export declare const ChangeMetadataSchema: z.ZodObject<{
     schema: z.ZodString;
     created: z.ZodOptional<z.ZodString>;

package/dist/core/change-metadata/schema.js

@@ -13,6 +13,16 @@ export const InitiativeLinkSchema = z.object({
     store: KebabIdentifierSchema('Store id'),
     id: KebabIdentifierSchema('Initiative id'),
 }).strict();
+/** Top-level keys ChangeMetadataSchema recognizes. Anything else is ignored. */
+export const CHANGE_METADATA_KNOWN_KEYS = [
+    'schema',
+    'created',
+    'goal',
+    'affected_areas',
+    'initiative',
+    'skip_specs',
+    'retire_capabilities',
+];
 // Per-change metadata schema. The schema field is validated against available
 // workflow schemas when metadata is read or written.
 export const ChangeMetadataSchema = z.object({

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

@@ -30,6 +30,14 @@ export interface ChangeNextStepsInput {
 export interface ActionContextInput {
     projectRoot: string;
     artifactIds: string[];
+    /**
+     * Set when the root is a store: the store holds the planning artifacts,
+     * and `implementationRoot` is the project that declares it, if any.
+     */
+    store?: {
+        id: string;
+        implementationRoot?: string;
+    };
 }
 export declare function summarizePlanningHome(planningHome: PlanningHome | undefined): PlanningHomeSummary | undefined;
 export declare function buildActionContext(input: ActionContextInput): ActionContext;