@codewalla_india/openspec 1.3.1 → 1.3.2

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

@@ -6,7 +6,23 @@ import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './typ
 export declare class ArtifactGraph {
     private artifacts;
     private schema;
+    /** Artifact id -> its position in the schema's `artifacts:` list. */
+    private declarationOrder;
     private constructor();
+    /**
+     * Orders artifact ids by where the schema declares them.
+     *
+     * The dependency graph leaves siblings tied - spec-driven's `specs` and
+     * `design` both require only `proposal`, so both become ready at the same
+     * time. Ties used to be broken alphabetically, which put `design` ahead of
+     * `specs` and made the CLI recommend the artifacts in an order that
+     * contradicted the schema's own documented sequence
+     * (proposal -> specs -> design -> tasks). Breaking ties by declaration order
+     * follows the sequence the schema author wrote, for built-in and custom
+     * schemas alike, and stays just as deterministic. Ids not in the schema sort
+     * last so the comparator stays total.
+     */
+    private compareByDeclarationOrder;
     /**
      * Creates an ArtifactGraph from a YAML file path.
      */
@@ -35,15 +51,6 @@ export declare class ArtifactGraph {
      * Gets the schema version.
      */
     getVersion(): number;
-    /**
-     * Builds reverse adjacency: artifact ID -> IDs of artifacts that depend on it.
-     */
-    private buildDependentsMap;
-    /**
-     * Returns all transitive downstream artifact IDs that depend on the given artifact,
-     * sorted by build order (excludes the source artifact itself).
-     */
-    getTransitiveDependents(artifactId: string): string[];
     /**
      * Computes the topological build order using Kahn's algorithm.
      * Returns artifact IDs in the order they should be built.
@@ -61,5 +68,17 @@ export declare class ArtifactGraph {
      * Gets blocked artifacts and their unmet dependencies.
      */
     getBlocked(completed: CompletedSet): BlockedArtifacts;
+    /**
+     * Gets all artifacts that depend on the given artifact (direct and transitive).
+     * Returns artifact IDs in reverse topological order (deepest dependents first).
+     * Throws an error if a circular dependency is detected.
+     */
+    getDependents(artifactId: string): string[];
+    /**
+     * Gets reverse topological order for updating artifacts.
+     * Returns artifact IDs in the order they should be updated (dependents before dependees).
+     * Throws an error if a circular dependency is detected.
+     */
+    getReverseUpdateOrder(): string[];
 }
 //# sourceMappingURL=graph.d.ts.map

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

@@ -6,9 +6,29 @@ import { loadSchema, parseSchema } from './schema.js';
 export class ArtifactGraph {
     artifacts;
     schema;
+    /** Artifact id -> its position in the schema's `artifacts:` list. */
+    declarationOrder;
     constructor(schema) {
         this.schema = schema;
         this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+        this.declarationOrder = new Map(schema.artifacts.map((a, index) => [a.id, index]));
+    }
+    /**
+     * Orders artifact ids by where the schema declares them.
+     *
+     * The dependency graph leaves siblings tied - spec-driven's `specs` and
+     * `design` both require only `proposal`, so both become ready at the same
+     * time. Ties used to be broken alphabetically, which put `design` ahead of
+     * `specs` and made the CLI recommend the artifacts in an order that
+     * contradicted the schema's own documented sequence
+     * (proposal -> specs -> design -> tasks). Breaking ties by declaration order
+     * follows the sequence the schema author wrote, for built-in and custom
+     * schemas alike, and stays just as deterministic. Ids not in the schema sort
+     * last so the comparator stays total.
+     */
+    compareByDeclarationOrder(a, b) {
+        return ((this.declarationOrder.get(a) ?? Number.MAX_SAFE_INTEGER) -
+            (this.declarationOrder.get(b) ?? Number.MAX_SAFE_INTEGER));
     }
     /**
      * Creates an ArtifactGraph from a YAML file path.
@@ -55,57 +75,27 @@ export class ArtifactGraph {
         return this.schema.version;
     }
     /**
-     * Builds reverse adjacency: artifact ID -> IDs of artifacts that depend on it.
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
      */
-    buildDependentsMap() {
+    getBuildOrder() {
+        const inDegree = new Map();
         const dependents = new Map();
+        // Initialize all artifacts
         for (const artifact of this.artifacts.values()) {
+            inDegree.set(artifact.id, artifact.requires.length);
             dependents.set(artifact.id, []);
         }
+        // Build reverse adjacency (who depends on whom)
         for (const artifact of this.artifacts.values()) {
             for (const req of artifact.requires) {
                 dependents.get(req).push(artifact.id);
             }
         }
-        return dependents;
-    }
-    /**
-     * Returns all transitive downstream artifact IDs that depend on the given artifact,
-     * sorted by build order (excludes the source artifact itself).
-     */
-    getTransitiveDependents(artifactId) {
-        if (!this.artifacts.has(artifactId)) {
-            return [];
-        }
-        const dependents = this.buildDependentsMap();
-        const collected = new Set();
-        const queue = [artifactId];
-        while (queue.length > 0) {
-            const current = queue.shift();
-            for (const dependentId of dependents.get(current) ?? []) {
-                if (!collected.has(dependentId)) {
-                    collected.add(dependentId);
-                    queue.push(dependentId);
-                }
-            }
-        }
-        return this.getBuildOrder().filter((id) => collected.has(id));
-    }
-    /**
-     * Computes the topological build order using Kahn's algorithm.
-     * Returns artifact IDs in the order they should be built.
-     */
-    getBuildOrder() {
-        const inDegree = new Map();
-        const dependents = this.buildDependentsMap();
-        // Initialize in-degrees
-        for (const artifact of this.artifacts.values()) {
-            inDegree.set(artifact.id, artifact.requires.length);
-        }
-        // Start with roots (in-degree 0), sorted for determinism
+        // Start with roots (in-degree 0), in declaration order for determinism
         const queue = [...this.artifacts.keys()]
             .filter(id => inDegree.get(id) === 0)
-            .sort();
+            .sort((a, b) => this.compareByDeclarationOrder(a, b));
         const result = [];
         while (queue.length > 0) {
             const current = queue.shift();
@@ -119,7 +109,10 @@ export class ArtifactGraph {
                     newlyReady.push(dep);
                 }
             }
-            queue.push(...newlyReady.sort());
+            // Re-sort the whole queue, not just the new arrivals: an artifact that
+            // has been waiting can be declared after one that just became ready.
+            queue.push(...newlyReady);
+            queue.sort((a, b) => this.compareByDeclarationOrder(a, b));
         }
         return result;
     }
@@ -137,8 +130,9 @@ export class ArtifactGraph {
                 ready.push(artifact.id);
             }
         }
-        // Sort for deterministic ordering
-        return ready.sort();
+        // Declaration order: deterministic, and the first entry is the artifact the
+        // schema wants written next.
+        return ready.sort((a, b) => this.compareByDeclarationOrder(a, b));
     }
     /**
      * Checks if all artifacts in the graph are completed.
@@ -162,10 +156,67 @@ export class ArtifactGraph {
             }
             const unmetDeps = artifact.requires.filter(req => !completed.has(req));
             if (unmetDeps.length > 0) {
-                blocked[artifact.id] = unmetDeps.sort();
+                blocked[artifact.id] = unmetDeps.sort((a, b) => this.compareByDeclarationOrder(a, b));
             }
         }
         return blocked;
     }
+    /**
+     * Gets all artifacts that depend on the given artifact (direct and transitive).
+     * Returns artifact IDs in reverse topological order (deepest dependents first).
+     * Throws an error if a circular dependency is detected.
+     */
+    getDependents(artifactId) {
+        if (!this.artifacts.has(artifactId)) {
+            throw new Error(`Artifact not found: ${artifactId}`);
+        }
+        const dependents = new Set();
+        const visited = new Set();
+        const visiting = new Set();
+        const dfs = (currentId) => {
+            if (visiting.has(currentId)) {
+                // Cycle detected
+                const cycle = Array.from(visiting).concat(currentId).join(' -> ');
+                throw new Error(`Circular dependency detected: ${cycle}`);
+            }
+            if (visited.has(currentId)) {
+                return;
+            }
+            visiting.add(currentId);
+            // Find all artifacts that depend on currentId
+            for (const artifact of this.artifacts.values()) {
+                if (artifact.requires.includes(currentId)) {
+                    dfs(artifact.id);
+                    dependents.add(artifact.id);
+                }
+            }
+            visiting.delete(currentId);
+            visited.add(currentId);
+        };
+        dfs(artifactId);
+        // Convert to array and sort by reverse build order (deepest first)
+        const buildOrder = this.getBuildOrder();
+        const dependentArray = Array.from(dependents);
+        // Sort by reverse position in build order (deepest dependents first)
+        // Use declaration order as tiebreaker for artifacts at same depth
+        return dependentArray.sort((a, b) => {
+            const posA = buildOrder.indexOf(a);
+            const posB = buildOrder.indexOf(b);
+            if (posA !== posB) {
+                return posB - posA; // Reverse order by depth
+            }
+            // Same depth: use declaration order (already in build order)
+            return this.compareByDeclarationOrder(a, b);
+        });
+    }
+    /**
+     * Gets reverse topological order for updating artifacts.
+     * Returns artifact IDs in the order they should be updated (dependents before dependees).
+     * Throws an error if a circular dependency is detected.
+     */
+    getReverseUpdateOrder() {
+        const buildOrder = this.getBuildOrder();
+        return buildOrder.reverse();
+    }
 }
 //# sourceMappingURL=graph.js.map

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

@@ -2,7 +2,7 @@ export { ArtifactSchema, SchemaYamlSchema, type Artifact, type SchemaYaml, type
 export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
 export { ArtifactGraph } from './graph.js';
 export { detectCompleted } from './state.js';
-export { artifactOutputExists, isGlobPattern, resolveArtifactOutputs } from './outputs.js';
+export { artifactOutputExists, isGlobPattern, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
 export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, type SchemaInfo, } from './resolver.js';
 export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, type ChangeContext, type LoadChangeContextOptions, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, type ArtifactPathSummary, } from './instruction-loader.js';
 export type { PlanningHomeSummary, ActionContext, } from '../change-status-policy.js';

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

@@ -6,7 +6,7 @@ export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
 export { ArtifactGraph } from './graph.js';
 // State detection
 export { detectCompleted } from './state.js';
-export { artifactOutputExists, isGlobPattern, resolveArtifactOutputs } from './outputs.js';
+export { artifactOutputExists, isGlobPattern, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
 // Schema resolution
 export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, } from './resolver.js';
 // Instruction loading

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

@@ -32,10 +32,18 @@ export interface ChangeContext {
     planningHome?: PlanningHome;
     /** Parsed change metadata, when present */
     metadata?: ChangeMetadata;
+    /**
+     * Artifact IDs counted as complete only because the change declares
+     * skip_specs, not because their files exist. Kept separate so status can
+     * render them as skipped rather than done.
+     */
+    skippedArtifacts?: Set<string>;
 }
 export interface LoadChangeContextOptions {
     changeDir?: string;
     planningHome?: PlanningHome;
+    /** Pre-read project config; suppresses schema resolution's fallback config read. */
+    projectConfig?: ProjectConfig | null;
 }
 /**
  * Enriched instructions for creating an artifact.
@@ -73,7 +81,17 @@ export interface ArtifactInstructions {
     dependencies: DependencyInfo[];
     /** Artifacts that become available after completing this one */
     unlocks: string[];
+    /** True when the change declares skip_specs and this artifact is skipped */
+    skipped?: boolean;
+    /** Present only when skipped: tells the consumer not to create the artifact */
+    warning?: string;
 }
+/**
+ * Warning attached to instructions for an artifact skipped via skip_specs.
+ * Carried in the JSON payload too, so agents driving the CLI with --json see
+ * the same do-not-create signal as the text output.
+ */
+export declare const SKIP_SPECS_INSTRUCTIONS_WARNING: string;
 /**
  * Dependency information including path and description.
  */
@@ -86,6 +104,8 @@ export interface DependencyInfo {
     path: string;
     /** Description of the dependency artifact */
     description: string;
+    /** True when the dependency is satisfied via skip_specs - no files exist to read */
+    skipped?: boolean;
 }
 /**
  * Status of a single artifact in the workflow.
@@ -95,8 +115,13 @@ export interface ArtifactStatus {
     id: string;
     /** Output path pattern */
     outputPath: string;
-    /** Status: done, ready, or blocked */
-    status: 'done' | 'ready' | 'blocked';
+    /** Status: done, skipped (via skip_specs), ready, or blocked */
+    status: 'done' | 'skipped' | 'ready' | 'blocked';
+    /** Artifact IDs this artifact directly requires (its `requires` edges).
+     * Present for every status so callers can compute the transitive required
+     * set even when the artifact is already `done` (file-existence status does
+     * not imply its dependencies exist). */
+    requires: string[];
     /** Missing dependencies (only for blocked) */
     missingDeps?: string[];
 }
@@ -119,7 +144,9 @@ export interface ChangeStatus {
     nextSteps: string[];
     /** Machine-readable action constraints for agents */
     actionContext: ActionContext;
-    /** Whether all artifacts are complete */
+    /** Whether all planning artifacts are complete */
+    isPlanningComplete: boolean;
+    /** Compatibility alias for isPlanningComplete */
     isComplete: boolean;
     /** Artifact IDs required before apply phase (from schema's apply.requires) */
     applyRequires: string[];

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

@@ -1,9 +1,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getSchemaDir, resolveSchema } from './resolver.js';
+import { getSchemaDir, resolveSchema, listSchemasWithInfo } from './resolver.js';
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
-import { resolveArtifactOutputs } from './outputs.js';
+import { resolveArtifactOutputPath, resolveArtifactOutputs } from './outputs.js';
 import { readChangeMetadata, resolveSchemaForChange } from '../../utils/change-metadata.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { buildActionContext, buildNextSteps, summarizePlanningHome, } from '../change-status-policy.js';
@@ -21,6 +21,13 @@ export class TemplateLoadError extends Error {
         this.name = 'TemplateLoadError';
     }
 }
+/**
+ * Warning attached to instructions for an artifact skipped via skip_specs.
+ * Carried in the JSON payload too, so agents driving the CLI with --json see
+ * the same do-not-create signal as the text output.
+ */
+export const SKIP_SPECS_INSTRUCTIONS_WARNING = 'This change declares skip_specs: true in .openspec.yaml (no spec-level behavior changes), so this artifact is skipped.\n' +
+    'Do not create spec files - they will conflict with that marker. If requirements now change, remove skip_specs from .openspec.yaml and rerun this command.';
 /**
  * Loads a template from a schema's templates directory.
  *
@@ -35,7 +42,14 @@ export function loadTemplate(schemaName, templatePath, projectRoot) {
     if (!schemaDir) {
         throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
     }
-    const templatePathOnDisk = path.join(schemaDir, 'templates', templatePath);
+    const templatesDir = path.join(schemaDir, 'templates');
+    const templatePathOnDisk = path.join(templatesDir, templatePath);
+    try {
+        FileSystemUtils.assertPathWithin(templatesDir, templatePathOnDisk);
+    }
+    catch (error) {
+        throw new TemplateLoadError(error instanceof Error ? error.message : String(error), templatePathOnDisk);
+    }
     if (!fs.existsSync(templatePathOnDisk)) {
         throw new TemplateLoadError(`Template not found: ${templatePathOnDisk}`, templatePathOnDisk);
     }
@@ -66,10 +80,29 @@ export function loadChangeContext(projectRoot, changeName, schemaName, options =
     const metadata = readChangeMetadata(changeDir, projectRoot) ?? undefined;
     const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName, projectRoot, {
         metadata: metadata ?? null,
+        projectConfig: options.projectConfig,
     });
     const schema = resolveSchema(resolvedSchemaName, projectRoot);
     const graph = ArtifactGraph.fromSchema(schema);
     const completed = detectCompleted(graph, changeDir);
+    // A change that declares skip_specs has no spec deltas by design, so
+    // artifacts generating into specs/ count as complete; otherwise the graph
+    // would block their dependents (e.g. tasks) on files that must not exist.
+    // Tracked separately so status renders them as skipped, not done.
+    const skippedArtifacts = new Set();
+    if (metadata?.skip_specs) {
+        for (const artifact of graph.getAllArtifacts()) {
+            // A schema may write generates as './specs/...' - the globs treat that
+            // identically to 'specs/...', so the skip set must too, or validate
+            // would honor the marker while instructions tell the agent to create
+            // the very files the conflict gate polices.
+            const generates = artifact.generates.replace(/^(?:\.\/)+/, '');
+            if (generates.startsWith('specs/') && !completed.has(artifact.id)) {
+                completed.add(artifact.id);
+                skippedArtifacts.add(artifact.id);
+            }
+        }
+    }
     return {
         graph,
         completed,
@@ -79,6 +112,7 @@ export function loadChangeContext(projectRoot, changeName, schemaName, options =
         projectRoot,
         ...(options.planningHome ? { planningHome: options.planningHome } : {}),
         ...(metadata ? { metadata } : {}),
+        ...(skippedArtifacts.size > 0 ? { skippedArtifacts } : {}),
     };
 }
 export function generateInstructions(context, artifactId, projectRoot, options = {}) {
@@ -87,7 +121,7 @@ export function generateInstructions(context, artifactId, projectRoot, options =
         throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
     }
     const templateContent = loadTemplate(context.schemaName, artifact.template, context.projectRoot);
-    const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
+    const dependencies = getDependencyInfo(artifact, context.graph, context.completed, context.skippedArtifacts);
     const unlocks = getUnlockedArtifacts(context.graph, artifactId);
     // Use projectRoot from context if not explicitly provided
     const effectiveProjectRoot = projectRoot ?? context.projectRoot;
@@ -101,10 +135,12 @@ export function generateInstructions(context, artifactId, projectRoot, options =
             // If config read fails, continue without config
         }
     }
-    // Validate rules artifact IDs if config has rules (only once per session)
+    // Validate rules artifact IDs if config has rules (only once per session).
+    // The rules map is global while each change can use a different schema, so a
+    // key is only "unknown" when it matches no artifact in ANY available schema.
     if (projectConfig?.rules) {
-        const validArtifactIds = new Set(context.graph.getAllArtifacts().map((a) => a.id));
-        const warnings = validateConfigRules(projectConfig.rules, validArtifactIds, context.schemaName);
+        const validArtifactIds = new Set(listSchemasWithInfo(effectiveProjectRoot ?? undefined).flatMap((s) => s.artifacts));
+        const warnings = validateConfigRules(projectConfig.rules, validArtifactIds);
         // Show each unique warning only once per session
         for (const warning of warnings) {
             if (!shownWarnings.has(warning)) {
@@ -115,7 +151,9 @@ export function generateInstructions(context, artifactId, projectRoot, options =
     }
     // Extract context and rules as separate fields (not prepended to template)
     const configContext = projectConfig?.context?.trim() || undefined;
-    const rulesForArtifact = projectConfig?.rules?.[artifactId];
+    const rulesForArtifact = projectConfig?.rules && Object.hasOwn(projectConfig.rules, artifactId)
+        ? projectConfig.rules[artifactId]
+        : undefined;
     const configRules = rulesForArtifact && rulesForArtifact.length > 0 ? rulesForArtifact : undefined;
     return {
         changeName: context.changeName,
@@ -124,13 +162,16 @@ export function generateInstructions(context, artifactId, projectRoot, options =
         changeDir: context.changeDir,
         planningHome: summarizePlanningHome(context.planningHome),
         outputPath: artifact.generates,
-        resolvedOutputPath: path.join(context.changeDir, artifact.generates),
+        resolvedOutputPath: resolveArtifactOutputPath(context.changeDir, artifact.generates),
         existingOutputPaths: resolveArtifactOutputs(context.changeDir, artifact.generates),
         description: artifact.description,
         instruction: artifact.instruction,
         context: configContext,
         rules: configRules,
         ...(options.references !== undefined ? { references: options.references } : {}),
+        ...(context.skippedArtifacts?.has(artifact.id)
+            ? { skipped: true, warning: SKIP_SPECS_INSTRUCTIONS_WARNING }
+            : {}),
         template: templateContent,
         dependencies,
         unlocks,
@@ -139,7 +180,7 @@ export function generateInstructions(context, artifactId, projectRoot, options =
 /**
  * Gets dependency info including paths and descriptions.
  */
-function getDependencyInfo(artifact, graph, completed) {
+function getDependencyInfo(artifact, graph, completed, skippedArtifacts) {
     return artifact.requires.map(id => {
         const depArtifact = graph.getArtifact(id);
         return {
@@ -147,11 +188,16 @@ function getDependencyInfo(artifact, graph, completed) {
             done: completed.has(id),
             path: depArtifact?.generates ?? id,
             description: depArtifact?.description ?? '',
+            ...(skippedArtifacts?.has(id) ? { skipped: true } : {}),
         };
     });
 }
 /**
  * Gets artifacts that become available after completing the given artifact.
+ *
+ * `getAllArtifacts()` already yields the schema's declaration order, so the list
+ * is returned as collected: sorting it alphabetically would have `unlocks` name
+ * the artifacts in a different order than `status` recommends them.
  */
 function getUnlockedArtifacts(graph, artifactId) {
     const unlocks = [];
@@ -160,7 +206,7 @@ function getUnlockedArtifacts(graph, artifactId) {
             unlocks.push(artifact.id);
         }
     }
-    return unlocks.sort();
+    return unlocks;
 }
 /**
  * Formats the status of all artifacts in a change.
@@ -179,14 +225,23 @@ export function formatChangeStatus(context, options = {}) {
     const artifactStatuses = artifacts.map(artifact => {
         artifactPaths[artifact.id] = {
             outputPath: artifact.generates,
-            resolvedOutputPath: path.join(context.changeDir, artifact.generates),
+            resolvedOutputPath: resolveArtifactOutputPath(context.changeDir, artifact.generates),
             existingOutputPaths: resolveArtifactOutputs(context.changeDir, artifact.generates),
         };
+        if (context.skippedArtifacts?.has(artifact.id)) {
+            return {
+                id: artifact.id,
+                outputPath: artifact.generates,
+                status: 'skipped',
+                requires: artifact.requires,
+            };
+        }
         if (context.completed.has(artifact.id)) {
             return {
                 id: artifact.id,
                 outputPath: artifact.generates,
                 status: 'done',
+                requires: artifact.requires,
             };
         }
         if (ready.has(artifact.id)) {
@@ -194,12 +249,14 @@ export function formatChangeStatus(context, options = {}) {
                 id: artifact.id,
                 outputPath: artifact.generates,
                 status: 'ready',
+                requires: artifact.requires,
             };
         }
         return {
             id: artifact.id,
             outputPath: artifact.generates,
             status: 'blocked',
+            requires: artifact.requires,
             missingDeps: blocked[artifact.id] ?? [],
         };
     });
@@ -215,6 +272,7 @@ export function formatChangeStatus(context, options = {}) {
         planningHome: summarizePlanningHome(context.planningHome),
         changeRoot: context.changeDir,
         artifactPaths,
+        isPlanningComplete: isComplete,
         isComplete,
         applyRequires,
         nextSteps: buildNextSteps({

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

@@ -2,6 +2,7 @@
  * Checks if a path contains glob pattern characters.
  */
 export declare function isGlobPattern(pattern: string): boolean;
+export declare function resolveArtifactOutputPath(changeDir: string, generates: string): string;
 /**
  * Resolves an artifact's output path(s) to concrete files that currently exist.
  * Returns absolute file paths. Glob matches are sorted for deterministic output.

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

@@ -8,16 +8,66 @@ import { FileSystemUtils } from '../../utils/file-system.js';
 export function isGlobPattern(pattern) {
     return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
 }
+export function resolveArtifactOutputPath(changeDir, generates) {
+    const outputPath = path.join(changeDir, generates);
+    FileSystemUtils.assertPathWithin(changeDir, outputPath);
+    return outputPath;
+}
+function assertGlobDirectoryTraversal(changeDir, currentDir, directorySegments, segmentIndex = 0, visited = new Set(), canonicalChangeDir = FileSystemUtils.canonicalizeExistingPath(changeDir), ancestors = new Set()) {
+    if (segmentIndex >= directorySegments.length)
+        return;
+    const canonicalDir = FileSystemUtils.canonicalizeExistingPath(currentDir);
+    FileSystemUtils.assertPathWithin(canonicalChangeDir, canonicalDir);
+    const visitKey = `${canonicalDir}\0${segmentIndex}`;
+    if (ancestors.has(visitKey)) {
+        throw new Error(`Cannot resolve artifact outputs through a linked directory cycle: ${currentDir}`);
+    }
+    if (visited.has(visitKey))
+        return;
+    visited.add(visitKey);
+    ancestors.add(visitKey);
+    try {
+        const segment = directorySegments[segmentIndex];
+        if (segment === '**') {
+            // `**` may consume no directory at all.
+            assertGlobDirectoryTraversal(changeDir, canonicalDir, directorySegments, segmentIndex + 1, visited, canonicalChangeDir, ancestors);
+        }
+        const matches = fg.sync(segment === '**' ? '*' : segment, {
+            cwd: canonicalDir,
+            onlyFiles: false,
+            followSymbolicLinks: false,
+            deep: 1,
+        });
+        for (const match of matches) {
+            const candidate = path.join(canonicalDir, match);
+            try {
+                if (!fs.statSync(candidate).isDirectory())
+                    continue;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            const canonicalCandidate = FileSystemUtils.canonicalizeExistingPath(candidate);
+            FileSystemUtils.assertPathWithin(canonicalChangeDir, canonicalCandidate);
+            assertGlobDirectoryTraversal(changeDir, canonicalCandidate, directorySegments, segment === '**' ? segmentIndex : segmentIndex + 1, visited, canonicalChangeDir, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(visitKey);
+    }
+}
 /**
  * Resolves an artifact's output path(s) to concrete files that currently exist.
  * Returns absolute file paths. Glob matches are sorted for deterministic output.
  */
 export function resolveArtifactOutputs(changeDir, generates) {
+    const outputPath = resolveArtifactOutputPath(changeDir, generates);
     if (!isGlobPattern(generates)) {
-        const fullPath = path.join(changeDir, generates);
         try {
-            return fs.statSync(fullPath).isFile()
-                ? [FileSystemUtils.canonicalizeExistingPath(fullPath)]
+            return fs.statSync(outputPath).isFile()
+                ? [FileSystemUtils.canonicalizeExistingPath(outputPath)]
                 : [];
         }
         catch {
@@ -25,9 +75,21 @@ export function resolveArtifactOutputs(changeDir, generates) {
         }
     }
     const normalizedPattern = FileSystemUtils.toPosixPath(generates);
+    assertGlobDirectoryTraversal(changeDir, changeDir, normalizedPattern.split('/').slice(0, -1));
     const matches = fg
-        .sync(normalizedPattern, { cwd: changeDir, onlyFiles: true, absolute: true })
-        .map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
+        .sync(normalizedPattern, {
+        cwd: changeDir,
+        onlyFiles: true,
+        absolute: true,
+        // Preserve existing support for linked artifact directories. Every
+        // concrete match is canonically confined below before it is returned.
+        followSymbolicLinks: true,
+    })
+        .map((match) => {
+        const normalizedMatch = path.normalize(match);
+        FileSystemUtils.assertPathWithin(changeDir, normalizedMatch);
+        return FileSystemUtils.canonicalizeExistingPath(normalizedMatch);
+    });
     return Array.from(new Set(matches)).sort();
 }
 /**