test: align path assertions with canonical helper

src/commands/workflow/instructions.ts

@@ -250,7 +250,7 @@ export async function generateApplyInstructions(
 ): Promise<ApplyInstructions> {
   // loadChangeContext will auto-detect schema from metadata if not provided
   const context = loadChangeContext(projectRoot, changeName, schemaName);
-  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+  const changeDir = context.changeDir;
 
   // Get the full schema to access the apply phase configuration
   const schema = resolveSchema(context.schemaName, projectRoot);

src/commands/workflow/templates.ts

@@ -11,6 +11,7 @@ import {
   getSchemaDir,
   ArtifactGraph,
 } from '../../core/artifact-graph/index.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
 import { validateSchemaExists, DEFAULT_SCHEMA } from './shared.js';
 
 // -----------------------------------------------------------------------------
@@ -68,7 +69,9 @@ export async function templatesCommand(options: TemplatesOptions): Promise<void>
 
     const templates: TemplateInfo[] = graph.getAllArtifacts().map((artifact) => ({
       artifactId: artifact.id,
-      templatePath: path.join(schemaDir, 'templates', artifact.template),
+      templatePath: FileSystemUtils.canonicalizeExistingPath(
+        path.join(schemaDir, 'templates', artifact.template)
+      ),
       source,
     }));
 

src/core/artifact-graph/instruction-loader.ts

@@ -4,6 +4,7 @@ import { getSchemaDir, resolveSchema } from './resolver.js';
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
 import { resolveSchemaForChange } from '../../utils/change-metadata.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
 import { readProjectConfig, validateConfigRules } from '../project-config.js';
 import type { Artifact, CompletedSet } from './types.js';
 
@@ -137,15 +138,17 @@ export function loadTemplate(
     );
   }
 
-  const fullPath = path.join(schemaDir, 'templates', templatePath);
+  const templatePathOnDisk = path.join(schemaDir, 'templates', templatePath);
 
-  if (!fs.existsSync(fullPath)) {
+  if (!fs.existsSync(templatePathOnDisk)) {
     throw new TemplateLoadError(
-      `Template not found: ${fullPath}`,
-      fullPath
+      `Template not found: ${templatePathOnDisk}`,
+      templatePathOnDisk
     );
   }
 
+  const fullPath = FileSystemUtils.canonicalizeExistingPath(templatePathOnDisk);
+
   try {
     return fs.readFileSync(fullPath, 'utf-8');
   } catch (err) {
@@ -175,7 +178,9 @@ export function loadChangeContext(
   changeName: string,
   schemaName?: string
 ): ChangeContext {
-  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+  const changeDir = FileSystemUtils.canonicalizeExistingPath(
+    path.join(projectRoot, 'openspec', 'changes', changeName)
+  );
 
   // Resolve schema: explicit > metadata > default
   const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);

src/core/artifact-graph/outputs.ts

@@ -19,14 +19,18 @@ export function resolveArtifactOutputs(changeDir: string, generates: string): st
 
   if (!isGlobPattern(generates)) {
     try {
-      return fs.statSync(fullPattern).isFile() ? [fullPattern] : [];
+      return fs.statSync(fullPattern).isFile()
+        ? [FileSystemUtils.canonicalizeExistingPath(fullPattern)]
+        : [];
     } catch {
       return [];
     }
   }
 
   const normalizedPattern = FileSystemUtils.toPosixPath(fullPattern);
-  const matches = fg.sync(normalizedPattern, { onlyFiles: true }).map((match) => path.normalize(match));
+  const matches = fg
+    .sync(normalizedPattern, { onlyFiles: true })
+    .map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
 
   return Array.from(new Set(matches)).sort();
 }

src/utils/file-system.ts

@@ -1,6 +1,9 @@
-import { promises as fs, constants as fsConstants } from 'fs';
+import * as nodeFs from 'fs';
 import path from 'path';
 
+const fs = nodeFs.promises;
+const { constants: fsConstants } = nodeFs;
+
 function isMarkerOnOwnLine(content: string, markerIndex: number, markerLength: number): boolean {
   let leftIndex = markerIndex - 1;
   while (leftIndex >= 0 && content[leftIndex] !== '\n') {
@@ -50,6 +53,23 @@ export class FileSystemUtils {
     return p.replace(/\\/g, '/');
   }
 
+  /**
+   * Returns a canonical absolute path when the target exists.
+   * Falls back to path.resolve() so callers can still produce a stable absolute path.
+   */
+  static canonicalizeExistingPath(targetPath: string): string {
+    try {
+      // Prefer the native resolver so Windows short-path aliases are expanded.
+      return nodeFs.realpathSync.native(targetPath);
+    } catch {
+      try {
+        return nodeFs.realpathSync(targetPath);
+      } catch {
+        return path.resolve(targetPath);
+      }
+    }
+  }
+
   private static isWindowsBasePath(basePath: string): boolean {
     return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
   }

test/commands/artifact-workflow.test.ts

@@ -3,11 +3,14 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { runCLI } from '../helpers/run-cli.js';
+import { FileSystemUtils } from '../../src/utils/file-system.js';
 
 describe('artifact-workflow CLI commands', () => {
   let tempDir: string;
   let changesDir: string;
 
+  const canonical = (targetPath: string): string => FileSystemUtils.canonicalizeExistingPath(targetPath);
+
   beforeEach(async () => {
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-artifact-workflow-'));
     changesDir = path.join(tempDir, 'openspec', 'changes');
@@ -411,10 +414,8 @@ describe('artifact-workflow CLI commands', () => {
       expect(result.stderr).toBe('');
 
       const json = JSON.parse(result.stdout);
-      const expectedProposalPath = await fs.realpath(path.join(changesDir, 'json-apply', 'proposal.md'));
-      const expectedSpecPath = await fs.realpath(
-        path.join(changesDir, 'json-apply', 'specs', 'test-spec.md')
-      );
+      const expectedProposalPath = canonical(path.join(changesDir, 'json-apply', 'proposal.md'));
+      const expectedSpecPath = canonical(path.join(changesDir, 'json-apply', 'specs', 'test-spec.md'));
       expect(json.changeName).toBe('json-apply');
       expect(json.schemaName).toBe('spec-driven');
       expect(json.state).toBe('ready');
@@ -472,7 +473,7 @@ apply:
       );
       expect(applyResult.exitCode).toBe(0);
       const applyJson = JSON.parse(applyResult.stdout);
-      const resolvedSpecPath = await fs.realpath(specPath);
+      const resolvedSpecPath = canonical(specPath);
       expect(applyJson.state).toBe('ready');
       expect(applyJson.missingArtifacts).toBeUndefined();
       expect(applyJson.contextFiles).toEqual({

test/core/artifact-graph/outputs.test.ts

@@ -2,11 +2,14 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import { FileSystemUtils } from '../../../src/utils/file-system.js';
 import { artifactOutputExists, resolveArtifactOutputs } from '../../../src/core/artifact-graph/outputs.js';
 
 describe('artifact-graph/outputs', () => {
   let tempDir: string;
 
+  const canonical = (targetPath: string): string => FileSystemUtils.canonicalizeExistingPath(targetPath);
+
   beforeEach(() => {
     tempDir = path.join(os.tmpdir(), `openspec-outputs-test-${Date.now()}`);
     fs.mkdirSync(tempDir, { recursive: true });
@@ -20,7 +23,7 @@ describe('artifact-graph/outputs', () => {
     const filePath = path.join(tempDir, 'proposal.md');
     fs.writeFileSync(filePath, 'content');
 
-    expect(resolveArtifactOutputs(tempDir, 'proposal.md')).toEqual([filePath]);
+    expect(resolveArtifactOutputs(tempDir, 'proposal.md')).toEqual([canonical(filePath)]);
     expect(artifactOutputExists(tempDir, 'proposal.md')).toBe(true);
   });
 
@@ -38,7 +41,7 @@ describe('artifact-graph/outputs', () => {
     fs.mkdirSync(nestedDir, { recursive: true });
     fs.writeFileSync(filePath, 'content');
 
-    expect(resolveArtifactOutputs(tempDir, 'specs/*/spec.md')).toEqual([filePath]);
+    expect(resolveArtifactOutputs(tempDir, 'specs/*/spec.md')).toEqual([canonical(filePath)]);
     expect(artifactOutputExists(tempDir, 'specs/*/spec.md')).toBe(true);
   });
 
@@ -50,7 +53,7 @@ describe('artifact-graph/outputs', () => {
     fs.writeFileSync(matching, 'content');
     fs.writeFileSync(nonMatching, 'content');
 
-    expect(resolveArtifactOutputs(tempDir, 'specs/foo*.md')).toEqual([matching]);
+    expect(resolveArtifactOutputs(tempDir, 'specs/foo*.md')).toEqual([canonical(matching)]);
   });
 
   it('supports question-mark glob patterns', () => {
@@ -60,7 +63,7 @@ describe('artifact-graph/outputs', () => {
     fs.writeFileSync(matching, 'content');
     fs.writeFileSync(path.join(specsDir, 'a10.md'), 'content');
 
-    expect(resolveArtifactOutputs(tempDir, 'specs/a?.md')).toEqual([matching]);
+    expect(resolveArtifactOutputs(tempDir, 'specs/a?.md')).toEqual([canonical(matching)]);
   });
 
   it('supports character class glob patterns', () => {
@@ -72,7 +75,31 @@ describe('artifact-graph/outputs', () => {
     fs.writeFileSync(bPath, 'content');
     fs.writeFileSync(path.join(specsDir, 'c.md'), 'content');
 
-    expect(resolveArtifactOutputs(tempDir, 'specs/[ab].md')).toEqual([aPath, bPath]);
+    expect(resolveArtifactOutputs(tempDir, 'specs/[ab].md')).toEqual([
+      canonical(aPath),
+      canonical(bPath),
+    ]);
+  });
+
+  it('canonicalizes resolved paths when the change directory is accessed through an alias', () => {
+    const rootDir = path.join(tempDir, 'workspace');
+    const realChangeDir = path.join(rootDir, 'real-change');
+    const aliasChangeDir = path.join(rootDir, 'alias-change');
+    const specDir = path.join(realChangeDir, 'specs', 'change-a');
+    const proposalPath = path.join(realChangeDir, 'proposal.md');
+    const specPath = path.join(specDir, 'spec.md');
+
+    fs.mkdirSync(specDir, { recursive: true });
+    fs.writeFileSync(proposalPath, 'content');
+    fs.writeFileSync(specPath, 'content');
+    fs.symlinkSync(realChangeDir, aliasChangeDir, process.platform === 'win32' ? 'junction' : 'dir');
+
+    expect(resolveArtifactOutputs(aliasChangeDir, 'proposal.md')).toEqual([
+      canonical(proposalPath),
+    ]);
+    expect(resolveArtifactOutputs(aliasChangeDir, 'specs/*/spec.md')).toEqual([
+      canonical(specPath),
+    ]);
   });
 
   it('returns an empty list when no files match the artifact output', () => {

test/utils/file-system.test.ts

@@ -1,4 +1,5 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as nodeFs from 'fs';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
@@ -92,6 +93,22 @@ describe('FileSystemUtils', () => {
     });
   });
 
+  describe('canonicalizeExistingPath', () => {
+    it('should prefer the native realpath resolver when available', async () => {
+      const filePath = path.join(testDir, 'canonical.txt');
+      await fs.writeFile(filePath, 'content');
+
+      const nativeSpy = vi.spyOn(nodeFs.realpathSync, 'native');
+
+      const resolved = FileSystemUtils.canonicalizeExistingPath(filePath);
+
+      expect(nativeSpy).toHaveBeenCalledWith(filePath);
+      expect(resolved).toBe(nodeFs.realpathSync.native(filePath));
+
+      nativeSpy.mockRestore();
+    });
+  });
+
   describe('writeFile', () => {
     it('should write content to file', async () => {
       const filePath = path.join(testDir, 'output.txt');