@fission-ai/openspec 1.6.0-beta.1 → 1.7.0

package/dist/core/archive.js

@@ -1,16 +1,25 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import { formatLocalDate } from '../utils/date.js';
 import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
 import { Validator } from './validation/validator.js';
 import chalk from 'chalk';
 import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from './root-selection.js';
 import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, } from './specs-apply.js';
+import { discoverSpecFiles, hasAnyFileUnder } from '../utils/spec-discovery.js';
+import { readSkipSpecsMarker } from '../utils/change-metadata.js';
 function isMissingPathError(error) {
     return (typeof error === 'object' &&
         error !== null &&
         'code' in error &&
         error.code === 'ENOENT');
 }
+/**
+ * Matches the `YYYY-MM-DD-` prefix that archiving prepends to a change name.
+ * A change whose name already starts with one (a common authoring convention)
+ * is archived under its existing name so the prefix is never stacked (#1309).
+ */
+const ARCHIVE_DATE_PREFIX_PATTERN = /^\d{4}-\d{2}-\d{2}-/;
 async function listActiveChangeNames(changesDir) {
     try {
         const entries = await fs.readdir(changesDir, { withFileTypes: true });
@@ -181,10 +190,21 @@ export class ArchiveCommand {
                 try {
                     await fs.access(changeFile);
                     const changeReport = await validator.validateChange(changeFile);
-                    // Proposal validation is informative only (do not block archive)
-                    if (!changeReport.valid) {
+                    // Proposal validation is informative only (do not block archive).
+                    // `validateChange` parses the change together with its delta specs,
+                    // so it also raises requirement-level issues under
+                    // `deltas.<n>.requirement(s)`. Those
+                    // are not proposal problems, and reporting them here was noisy and
+                    // sometimes wrong (#498): the change parser records every requirement
+                    // under both `requirement` and `requirements`, so each defect was
+                    // printed twice, and REMOVED requirements — names-only by design —
+                    // produced a "missing scenario" warning for a correct removal.
+                    // Genuine delta defects are still caught below, by the delta spec
+                    // validation and by the rebuilt-spec check that runs before any write.
+                    const proposalIssues = changeReport.issues.filter((issue) => !/^deltas\.\d+\.requirements?\./.test(issue.path));
+                    if (!changeReport.valid && proposalIssues.length > 0) {
                         console.log(chalk.yellow(`\nProposal warnings in proposal.md (non-blocking):`));
-                        for (const issue of changeReport.issues) {
+                        for (const issue of proposalIssues) {
                             const symbol = issue.level === 'ERROR' ? '⚠' : (issue.level === 'WARNING' ? '⚠' : 'ℹ');
                             console.log(chalk.yellow(`  ${symbol} ${issue.message}`));
                         }
@@ -196,25 +216,52 @@ export class ArchiveCommand {
             }
             // Validate delta-formatted spec files under the change directory if present
             const changeSpecsDir = path.join(changeDir, 'specs');
-            let hasDeltaSpecs = false;
-            try {
-                const candidates = await fs.readdir(changeSpecsDir, { withFileTypes: true });
-                for (const c of candidates) {
-                    if (c.isDirectory()) {
-                        try {
-                            const candidatePath = path.join(changeSpecsDir, c.name, 'spec.md');
-                            await fs.access(candidatePath);
-                            const content = await fs.readFile(candidatePath, 'utf-8');
-                            if (/^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/m.test(content)) {
-                                hasDeltaSpecs = true;
-                                break;
-                            }
-                        }
-                        catch { }
+            // A spec.md at the specs/ root is never merged, so archiving a change
+            // that has one drops its content whether or not it carries delta headers
+            // (#1385). Its existence alone must run validation, which reports it and
+            // blocks the archive. A directory named spec.md is a normal capability
+            // folder, so only a regular file counts.
+            const rootSpecStat = await fs.stat(path.join(changeSpecsDir, 'spec.md')).catch(() => null);
+            let hasDeltaSpecs = rootSpecStat?.isFile() === true;
+            // 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
+            // happen to have no delta headers. A marker that cannot be honored
+            // (skip_specs mentioned but the metadata fails the shared shape, or
+            // names a schema that does not resolve) also
+            // forces validation, so archive and validate always agree about the
+            // marker. Unreadable specs/ fails closed into validation too. (An
+            // UNMARKED zero-delta change still archives with only non-blocking
+            // proposal warnings — a gap that predates the marker and is left
+            // unchanged here.)
+            if (!hasDeltaSpecs) {
+                const marker = readSkipSpecsMarker(changeDir);
+                if (marker.invalidReason) {
+                    hasDeltaSpecs = true;
+                }
+                else if (marker.declared) {
+                    let specsDirHasFiles = true;
+                    try {
+                        specsDirHasFiles = await hasAnyFileUnder(changeSpecsDir);
                     }
+                    catch {
+                        // fall through with true: let validation surface the conflict
+                    }
+                    hasDeltaSpecs = specsDirHasFiles;
                 }
             }
-            catch { }
+            for (const { specFile } of hasDeltaSpecs ? [] : await discoverSpecFiles(changeSpecsDir)) {
+                try {
+                    const content = await fs.readFile(specFile, 'utf-8');
+                    // Case-insensitive to match the delta parser, so a lowercase header
+                    // routes through the same delta validation that validate runs.
+                    if (/^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/im.test(content)) {
+                        hasDeltaSpecs = true;
+                        break;
+                    }
+                }
+                catch { }
+            }
             if (hasDeltaSpecs) {
                 const deltaReport = await validator.validateChangeDeltaSpecs(changeDir);
                 if (!deltaReport.valid) {
@@ -298,6 +345,7 @@ export class ArchiveCommand {
         // Handle spec updates unless skipSpecs flag is set
         let specsUpdated = false;
         let totals;
+        const specWarnings = [];
         if (options.skipSpecs) {
             if (!json) {
                 console.log('Skipping spec updates (--skip-specs flag provided).');
@@ -311,7 +359,7 @@ export class ArchiveCommand {
                     console.log('\nSpecs to update:');
                     for (const update of specUpdates) {
                         const status = update.exists ? 'update' : 'create';
-                        const capability = path.basename(path.dirname(update.target));
+                        const capability = update.id;
                         console.log(`  ${capability}: ${status}`);
                     }
                 }
@@ -336,6 +384,9 @@ export class ArchiveCommand {
                         for (const update of specUpdates) {
                             const built = await buildUpdatedSpec(update, changeName, { silent: json });
                             prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+                            // Carried into the result so JSON mode (where nothing was
+                            // printed) still surfaces them; human mode discards the result.
+                            specWarnings.push(...built.warnings);
                         }
                     }
                     catch (err) {
@@ -351,7 +402,7 @@ export class ArchiveCommand {
                     // late validation failure really does leave all targets unchanged.
                     if (!skipValidation) {
                         for (const p of prepared) {
-                            const specName = path.basename(path.dirname(p.update.target));
+                            const specName = p.update.id;
                             const report = await new Validator().validateSpecContent(specName, p.rebuilt);
                             if (!report.valid) {
                                 if (json) {
@@ -372,28 +423,43 @@ export class ArchiveCommand {
                     }
                     // All validations passed; write files and display counts
                     const writeTotals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+                    let wroteAny = false;
                     for (const p of prepared) {
+                        const { added, modified, removed, renamed } = p.counts;
+                        if (added + modified + removed + renamed === 0) {
+                            // Every operation was already synced: rewriting the file would
+                            // only churn normalization differences into it.
+                            continue;
+                        }
                         await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
                             silent: json,
                             // Cross-root paths must be absolute when a store is selected.
                             ...(isStoreSelectedRoot(root) ? { displayPath: p.update.target } : {}),
                         });
-                        writeTotals.added += p.counts.added;
-                        writeTotals.modified += p.counts.modified;
-                        writeTotals.removed += p.counts.removed;
-                        writeTotals.renamed += p.counts.renamed;
+                        wroteAny = true;
+                        writeTotals.added += added;
+                        writeTotals.modified += modified;
+                        writeTotals.removed += removed;
+                        writeTotals.renamed += renamed;
                     }
-                    specsUpdated = true;
+                    specsUpdated = wroteAny;
                     totals = writeTotals;
                     if (!json) {
                         console.log(`Totals: + ${writeTotals.added}, ~ ${writeTotals.modified}, - ${writeTotals.removed}, → ${writeTotals.renamed}`);
-                        console.log('Specs updated successfully.');
+                        console.log(wroteAny
+                            ? 'Specs updated successfully.'
+                            : 'Specs already in sync; no files changed.');
                     }
                 }
             }
         }
-        // Create archive directory with date prefix
-        const archiveName = `${this.getArchiveDate()}-${changeName}`;
+        // Create archive directory with date prefix. Names that already carry
+        // one keep it: re-prefixing would stutter the name, and when the archive
+        // runs on a later day the folder would sort under a day on which the
+        // change did not happen (#1309).
+        const archiveName = ARCHIVE_DATE_PREFIX_PATTERN.test(changeName)
+            ? changeName
+            : `${formatLocalDate()}-${changeName}`;
         const archivePath = path.join(archiveDir, archiveName);
         // Check if archive already exists
         let archiveExists = false;
@@ -422,6 +488,7 @@ export class ArchiveCommand {
             path: archivePath,
             specsUpdated,
             ...(totals ? { totals } : {}),
+            ...(specWarnings.length > 0 ? { warnings: specWarnings } : {}),
         };
     }
     async selectChange(changesDir) {
@@ -462,9 +529,5 @@ export class ArchiveCommand {
             return null;
         }
     }
-    getArchiveDate() {
-        // Returns date in YYYY-MM-DD format
-        return new Date().toISOString().split('T')[0];
-    }
 }
 //# sourceMappingURL=archive.js.map

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.
      */

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.
@@ -72,10 +92,10 @@ export class ArtifactGraph {
                 dependents.get(req).push(artifact.id);
             }
         }
-        // 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();
@@ -89,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;
     }
@@ -107,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.
@@ -132,7 +156,7 @@ 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;

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[];
 }

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

@@ -1,6 +1,6 @@
 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';
@@ -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.
  *
@@ -66,10 +73,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 +105,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 +114,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 +128,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)) {
@@ -131,6 +160,9 @@ export function generateInstructions(context, artifactId, projectRoot, options =
         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 +171,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 +179,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 +197,7 @@ function getUnlockedArtifacts(graph, artifactId) {
             unlocks.push(artifact.id);
         }
     }
-    return unlocks.sort();
+    return unlocks;
 }
 /**
  * Formats the status of all artifacts in a change.
@@ -182,11 +219,20 @@ export function formatChangeStatus(context, options = {}) {
             resolvedOutputPath: path.join(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 +240,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] ?? [],
         };
     });

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

@@ -1,3 +1,4 @@
+import * as fs from 'node:fs';
 import type { SchemaYaml } from './types.js';
 /**
  * Error thrown when loading a schema fails.
@@ -22,6 +23,19 @@ export declare function getUserSchemasDir(): string;
  * @returns The path to the project's schemas directory
  */
 export declare function getProjectSchemasDir(projectRoot: string): string;
+/**
+ * Determines whether a directory entry represents a schema directory candidate.
+ *
+ * Returns true for real directories and for symlinks whose target is a
+ * directory. `fs.Dirent.isDirectory()` reports the raw entry type, so a symlink
+ * (even one pointing at a directory) has `isDirectory() === false`; we
+ * dereference such entries via `fs.statSync` to admit symlinked schema dirs
+ * while still rejecting symlinks-to-files and broken/dangling symlinks.
+ *
+ * @param parentDir - The directory containing the entry
+ * @param entry - The directory entry from `fs.readdirSync(..., { withFileTypes: true })`
+ */
+export declare function isSchemaDir(parentDir: string, entry: fs.Dirent): boolean;
 /**
  * Resolves a schema name to its directory path.
  *

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

@@ -39,6 +39,34 @@ export function getUserSchemasDir() {
 export function getProjectSchemasDir(projectRoot) {
     return path.join(projectRoot, 'openspec', 'schemas');
 }
+/**
+ * Determines whether a directory entry represents a schema directory candidate.
+ *
+ * Returns true for real directories and for symlinks whose target is a
+ * directory. `fs.Dirent.isDirectory()` reports the raw entry type, so a symlink
+ * (even one pointing at a directory) has `isDirectory() === false`; we
+ * dereference such entries via `fs.statSync` to admit symlinked schema dirs
+ * while still rejecting symlinks-to-files and broken/dangling symlinks.
+ *
+ * @param parentDir - The directory containing the entry
+ * @param entry - The directory entry from `fs.readdirSync(..., { withFileTypes: true })`
+ */
+export function isSchemaDir(parentDir, entry) {
+    if (entry.isDirectory()) {
+        return true;
+    }
+    if (entry.isSymbolicLink()) {
+        try {
+            // statSync follows the link; isDirectory() reflects the target type.
+            return fs.statSync(path.join(parentDir, entry.name)).isDirectory();
+        }
+        catch {
+            // Broken symlink (dangling target) — statSync throws; treat as non-dir.
+            return false;
+        }
+    }
+    return false;
+}
 /**
  * Resolves a schema name to its directory path.
  *
@@ -134,7 +162,7 @@ export function listSchemas(projectRoot) {
     const packageDir = getPackageSchemasDir();
     if (fs.existsSync(packageDir)) {
         for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
-            if (entry.isDirectory()) {
+            if (isSchemaDir(packageDir, entry)) {
                 const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
                 if (fs.existsSync(schemaPath)) {
                     schemas.add(entry.name);
@@ -146,7 +174,7 @@ export function listSchemas(projectRoot) {
     const userDir = getUserSchemasDir();
     if (fs.existsSync(userDir)) {
         for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
-            if (entry.isDirectory()) {
+            if (isSchemaDir(userDir, entry)) {
                 const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
                 if (fs.existsSync(schemaPath)) {
                     schemas.add(entry.name);
@@ -159,7 +187,7 @@ export function listSchemas(projectRoot) {
         const projectDir = getProjectSchemasDir(projectRoot);
         if (fs.existsSync(projectDir)) {
             for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
-                if (entry.isDirectory()) {
+                if (isSchemaDir(projectDir, entry)) {
                     const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
                     if (fs.existsSync(schemaPath)) {
                         schemas.add(entry.name);
@@ -184,7 +212,7 @@ export function listSchemasWithInfo(projectRoot) {
         const projectDir = getProjectSchemasDir(projectRoot);
         if (fs.existsSync(projectDir)) {
             for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
-                if (entry.isDirectory()) {
+                if (isSchemaDir(projectDir, entry)) {
                     const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
                     if (fs.existsSync(schemaPath)) {
                         try {
@@ -209,7 +237,7 @@ export function listSchemasWithInfo(projectRoot) {
     const userDir = getUserSchemasDir();
     if (fs.existsSync(userDir)) {
         for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
-            if (entry.isDirectory() && !seenNames.has(entry.name)) {
+            if (isSchemaDir(userDir, entry) && !seenNames.has(entry.name)) {
                 const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
                 if (fs.existsSync(schemaPath)) {
                     try {
@@ -233,7 +261,7 @@ export function listSchemasWithInfo(projectRoot) {
     const packageDir = getPackageSchemasDir();
     if (fs.existsSync(packageDir)) {
         for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
-            if (entry.isDirectory() && !seenNames.has(entry.name)) {
+            if (isSchemaDir(packageDir, entry) && !seenNames.has(entry.name)) {
                 const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
                 if (fs.existsSync(schemaPath)) {
                     try {