@fission-ai/openspec 1.3.0 → 1.3.1

package/README.md

@@ -42,10 +42,6 @@ Our philosophy:
   Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
 
-### Teams
-
-Using OpenSpec in a team? [Email here](mailto:teams@openspec.dev) for access to our Slack channel.
-
 <!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
 
 ## See it in action

package/dist/commands/workflow/instructions.js

@@ -7,13 +7,13 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
 export async function instructionsCommand(artifactId, options) {
-    const spinner = ora('Generating instructions...').start();
+    const spinner = options.json ? undefined : ora('Generating instructions...').start();
     try {
         const projectRoot = process.cwd();
         const changeName = await validateChangeExists(options.change, projectRoot);
@@ -24,19 +24,19 @@ export async function instructionsCommand(artifactId, options) {
         // loadChangeContext will auto-detect schema from metadata if not provided
         const context = loadChangeContext(projectRoot, changeName, options.schema);
         if (!artifactId) {
-            spinner.stop();
+            spinner?.stop();
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
             throw new Error(`Missing required argument <artifact>. Valid artifacts:\n  ${validIds.join('\n  ')}`);
         }
         const artifact = context.graph.getArtifact(artifactId);
         if (!artifact) {
-            spinner.stop();
+            spinner?.stop();
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
             throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
         }
         const instructions = generateInstructions(context, artifactId, projectRoot);
         const isBlocked = instructions.dependencies.some((d) => !d.done);
-        spinner.stop();
+        spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify(instructions, null, 2));
             return;
@@ -44,7 +44,7 @@ export async function instructionsCommand(artifactId, options) {
         printInstructionsText(instructions, isBlocked);
     }
     catch (error) {
-        spinner.stop();
+        spinner?.stop();
         throw error;
     }
 }
@@ -161,63 +161,6 @@ function parseTasksFile(content) {
     }
     return tasks;
 }
-/**
- * Checks if an artifact output exists in the change directory.
- * Supports glob patterns (e.g., "specs/*.md") by verifying at least one matching file exists.
- */
-function artifactOutputExists(changeDir, generates) {
-    // Normalize the generates path to use platform-specific separators
-    const normalizedGenerates = generates.split('/').join(path.sep);
-    const fullPath = path.join(changeDir, normalizedGenerates);
-    // If it's a glob pattern (contains ** or *), check for matching files
-    if (generates.includes('*')) {
-        // Extract the directory part before the glob pattern
-        const parts = normalizedGenerates.split(path.sep);
-        const dirParts = [];
-        let patternPart = '';
-        for (const part of parts) {
-            if (part.includes('*')) {
-                patternPart = part;
-                break;
-            }
-            dirParts.push(part);
-        }
-        const dirPath = path.join(changeDir, ...dirParts);
-        // Check if directory exists
-        if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
-            return false;
-        }
-        // Extract expected extension from pattern (e.g., "*.md" -> ".md")
-        const extMatch = patternPart.match(/\*(\.[a-zA-Z0-9]+)$/);
-        const expectedExt = extMatch ? extMatch[1] : null;
-        // Recursively check for matching files
-        const hasMatchingFiles = (dir) => {
-            try {
-                const entries = fs.readdirSync(dir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isDirectory()) {
-                        // For ** patterns, recurse into subdirectories
-                        if (generates.includes('**') && hasMatchingFiles(path.join(dir, entry.name))) {
-                            return true;
-                        }
-                    }
-                    else if (entry.isFile()) {
-                        // Check if file matches expected extension (or any file if no extension specified)
-                        if (!expectedExt || entry.name.endsWith(expectedExt)) {
-                            return true;
-                        }
-                    }
-                }
-            }
-            catch {
-                return false;
-            }
-            return false;
-        };
-        return hasMatchingFiles(dirPath);
-    }
-    return fs.existsSync(fullPath);
-}
 /**
  * Generates apply instructions for implementing tasks from a change.
  * Schema-aware: reads apply phase configuration from schema to determine
@@ -226,7 +169,7 @@ function artifactOutputExists(changeDir, generates) {
 export async function generateApplyInstructions(projectRoot, changeName, schemaName) {
     // 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);
     const applyConfig = schema.apply;
@@ -239,15 +182,16 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     const missingArtifacts = [];
     for (const artifactId of requiredArtifactIds) {
         const artifact = schema.artifacts.find((a) => a.id === artifactId);
-        if (artifact && !artifactOutputExists(changeDir, artifact.generates)) {
+        if (artifact && resolveArtifactOutputs(changeDir, artifact.generates).length === 0) {
             missingArtifacts.push(artifactId);
         }
     }
     // Build context files from all existing artifacts in schema
     const contextFiles = {};
     for (const artifact of schema.artifacts) {
-        if (artifactOutputExists(changeDir, artifact.generates)) {
-            contextFiles[artifact.id] = path.join(changeDir, artifact.generates);
+        const outputs = resolveArtifactOutputs(changeDir, artifact.generates);
+        if (outputs.length > 0) {
+            contextFiles[artifact.id] = outputs;
         }
     }
     // Parse tasks if tracking file exists
@@ -310,7 +254,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     };
 }
 export async function applyInstructionsCommand(options) {
-    const spinner = ora('Generating apply instructions...').start();
+    const spinner = options.json ? undefined : ora('Generating apply instructions...').start();
     try {
         const projectRoot = process.cwd();
         const changeName = await validateChangeExists(options.change, projectRoot);
@@ -320,7 +264,7 @@ export async function applyInstructionsCommand(options) {
         }
         // generateApplyInstructions uses loadChangeContext which auto-detects schema
         const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema);
-        spinner.stop();
+        spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify(instructions, null, 2));
             return;
@@ -328,7 +272,7 @@ export async function applyInstructionsCommand(options) {
         printApplyInstructionsText(instructions);
     }
     catch (error) {
-        spinner.stop();
+        spinner?.stop();
         throw error;
     }
 }
@@ -349,8 +293,10 @@ export function printApplyInstructionsText(instructions) {
     const contextFileEntries = Object.entries(contextFiles);
     if (contextFileEntries.length > 0) {
         console.log('### Context Files');
-        for (const [artifactId, filePath] of contextFileEntries) {
-            console.log(`- ${artifactId}: ${filePath}`);
+        for (const [artifactId, filePaths] of contextFileEntries) {
+            for (const filePath of filePaths) {
+                console.log(`- ${artifactId}: ${filePath}`);
+            }
         }
         console.log();
     }

package/dist/commands/workflow/shared.d.ts

@@ -13,7 +13,7 @@ export interface ApplyInstructions {
     changeName: string;
     changeDir: string;
     schemaName: string;
-    contextFiles: Record<string, string>;
+    contextFiles: Record<string, string[]>;
     progress: {
         total: number;
         complete: number;

package/dist/commands/workflow/status.js

@@ -11,7 +11,7 @@ import { validateChangeExists, validateSchemaExists, getAvailableChanges, getSta
 // Command Implementation
 // -----------------------------------------------------------------------------
 export async function statusCommand(options) {
-    const spinner = ora('Loading change status...').start();
+    const spinner = options.json ? undefined : ora('Loading change status...').start();
     try {
         const projectRoot = process.cwd();
         // Handle no-changes case gracefully — status is informational,
@@ -19,7 +19,7 @@ export async function statusCommand(options) {
         if (!options.change) {
             const available = await getAvailableChanges(projectRoot);
             if (available.length === 0) {
-                spinner.stop();
+                spinner?.stop();
                 if (options.json) {
                     console.log(JSON.stringify({ changes: [], message: 'No active changes.' }, null, 2));
                     return;
@@ -28,7 +28,7 @@ export async function statusCommand(options) {
                 return;
             }
             // Changes exist but --change not provided
-            spinner.stop();
+            spinner?.stop();
             throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
         }
         const changeName = await validateChangeExists(options.change, projectRoot);
@@ -39,7 +39,7 @@ export async function statusCommand(options) {
         // loadChangeContext will auto-detect schema from metadata if not provided
         const context = loadChangeContext(projectRoot, changeName, options.schema);
         const status = formatChangeStatus(context);
-        spinner.stop();
+        spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify(status, null, 2));
             return;
@@ -47,7 +47,7 @@ export async function statusCommand(options) {
         printStatusText(status);
     }
     catch (error) {
-        spinner.stop();
+        spinner?.stop();
         throw error;
     }
 }

package/dist/commands/workflow/templates.js

@@ -6,12 +6,13 @@
 import ora from 'ora';
 import path from 'path';
 import { resolveSchema, getSchemaDir, ArtifactGraph, } from '../../core/artifact-graph/index.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
 import { validateSchemaExists, DEFAULT_SCHEMA } from './shared.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
 // -----------------------------------------------------------------------------
 export async function templatesCommand(options) {
-    const spinner = ora('Loading templates...').start();
+    const spinner = options.json ? undefined : ora('Loading templates...').start();
     try {
         const projectRoot = process.cwd();
         const schemaName = validateSchemaExists(options.schema ?? DEFAULT_SCHEMA, projectRoot);
@@ -40,10 +41,10 @@ export async function templatesCommand(options) {
         }
         const templates = graph.getAllArtifacts().map((artifact) => ({
             artifactId: artifact.id,
-            templatePath: path.join(schemaDir, 'templates', artifact.template),
+            templatePath: FileSystemUtils.canonicalizeExistingPath(path.join(schemaDir, 'templates', artifact.template)),
             source,
         }));
-        spinner.stop();
+        spinner?.stop();
         if (options.json) {
             const output = {};
             for (const t of templates) {
@@ -61,7 +62,7 @@ export async function templatesCommand(options) {
         }
     }
     catch (error) {
-        spinner.stop();
+        spinner?.stop();
         throw error;
     }
 }

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

@@ -2,6 +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 { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, type SchemaInfo, } from './resolver.js';
 export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, type ChangeContext, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, } from './instruction-loader.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -6,6 +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';
 // Schema resolution
 export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, } from './resolver.js';
 // Instruction loading

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

@@ -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';
 // Session-level cache for validation warnings (avoid repeating same warnings)
 const shownWarnings = new Set();
@@ -32,10 +33,11 @@ export function loadTemplate(schemaName, templatePath, projectRoot) {
     if (!schemaDir) {
         throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
     }
-    const fullPath = path.join(schemaDir, 'templates', templatePath);
-    if (!fs.existsSync(fullPath)) {
-        throw new TemplateLoadError(`Template not found: ${fullPath}`, fullPath);
+    const templatePathOnDisk = path.join(schemaDir, 'templates', templatePath);
+    if (!fs.existsSync(templatePathOnDisk)) {
+        throw new TemplateLoadError(`Template not found: ${templatePathOnDisk}`, templatePathOnDisk);
     }
+    const fullPath = FileSystemUtils.canonicalizeExistingPath(templatePathOnDisk);
     try {
         return fs.readFileSync(fullPath, 'utf-8');
     }
@@ -58,7 +60,7 @@ export function loadTemplate(schemaName, templatePath, projectRoot) {
  * @returns Change context with graph, completed set, and metadata
  */
 export function loadChangeContext(projectRoot, changeName, schemaName) {
-    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);
     const schema = resolveSchema(resolvedSchemaName, projectRoot);

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

@@ -0,0 +1,14 @@
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+export declare function isGlobPattern(pattern: string): boolean;
+/**
+ * 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 declare function resolveArtifactOutputs(changeDir: string, generates: string): string[];
+/**
+ * Checks if an artifact has at least one resolved output file.
+ */
+export declare function artifactOutputExists(changeDir: string, generates: string): boolean;
+//# sourceMappingURL=outputs.d.ts.map

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

@@ -0,0 +1,39 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import { FileSystemUtils } from '../../utils/file-system.js';
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+export function isGlobPattern(pattern) {
+    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+}
+/**
+ * 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) {
+    if (!isGlobPattern(generates)) {
+        const fullPath = path.join(changeDir, generates);
+        try {
+            return fs.statSync(fullPath).isFile()
+                ? [FileSystemUtils.canonicalizeExistingPath(fullPath)]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    const normalizedPattern = FileSystemUtils.toPosixPath(generates);
+    const matches = fg
+        .sync(normalizedPattern, { cwd: changeDir, onlyFiles: true, absolute: true })
+        .map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
+    return Array.from(new Set(matches)).sort();
+}
+/**
+ * Checks if an artifact has at least one resolved output file.
+ */
+export function artifactOutputExists(changeDir, generates) {
+    return resolveArtifactOutputs(changeDir, generates).length > 0;
+}
+//# sourceMappingURL=outputs.js.map

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

@@ -1,7 +1,5 @@
 import * as fs from 'node:fs';
-import * as path from 'node:path';
-import fg from 'fast-glob';
-import { FileSystemUtils } from '../../utils/file-system.js';
+import { artifactOutputExists } from './outputs.js';
 /**
  * Detects which artifacts are completed by checking file existence in the change directory.
  * Returns a Set of completed artifact IDs.
@@ -28,27 +26,6 @@ export function detectCompleted(graph, changeDir) {
  * Supports both simple paths and glob patterns.
  */
 function isArtifactComplete(generates, changeDir) {
-    const fullPattern = path.join(changeDir, generates);
-    // Check if it's a glob pattern
-    if (isGlobPattern(generates)) {
-        return hasGlobMatches(fullPattern);
-    }
-    // Simple file path - check if file exists
-    return fs.existsSync(fullPattern);
-}
-/**
- * Checks if a path contains glob pattern characters.
- */
-function isGlobPattern(pattern) {
-    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
-}
-/**
- * Checks if a glob pattern has any matches.
- * Normalizes Windows backslashes to forward slashes for cross-platform glob compatibility.
- */
-function hasGlobMatches(pattern) {
-    const normalizedPattern = FileSystemUtils.toPosixPath(pattern);
-    const matches = fg.sync(normalizedPattern, { onlyFiles: true });
-    return matches.length > 0;
+    return artifactOutputExists(changeDir, generates);
 }
 //# sourceMappingURL=state.js.map

package/dist/core/parsers/change-parser.js

@@ -148,15 +148,19 @@ export class ChangeParser extends MarkdownParser {
     parseSectionsFromContent(content) {
         const normalizedContent = ChangeParser.normalizeContent(content);
         const lines = normalizedContent.split('\n');
+        const codeFenceLineMask = ChangeParser.buildCodeFenceMask(lines);
         const sections = [];
         const stack = [];
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
+            if (codeFenceLineMask[i]) {
+                continue;
+            }
             const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
             if (headerMatch) {
                 const level = headerMatch[1].length;
                 const title = headerMatch[2].trim();
-                const contentLines = this.getContentUntilNextHeaderFromLines(lines, i + 1, level);
+                const contentLines = this.getContentUntilNextHeaderFromLines(lines, codeFenceLineMask, i + 1, level);
                 const section = {
                     level,
                     title,
@@ -177,11 +181,11 @@ export class ChangeParser extends MarkdownParser {
         }
         return sections;
     }
-    getContentUntilNextHeaderFromLines(lines, startLine, currentLevel) {
+    getContentUntilNextHeaderFromLines(lines, codeFenceLineMask, startLine, currentLevel) {
         const contentLines = [];
         for (let i = startLine; i < lines.length; i++) {
             const line = lines[i];
-            const headerMatch = line.match(/^(#{1,6})\s+/);
+            const headerMatch = codeFenceLineMask[i] ? null : line.match(/^(#{1,6})\s+/);
             if (headerMatch && headerMatch[1].length <= currentLevel) {
                 break;
             }

package/dist/core/parsers/markdown-parser.d.ts

@@ -7,9 +7,13 @@ export interface Section {
 }
 export declare class MarkdownParser {
     private lines;
+    private codeFenceLineMask;
     private currentLine;
     constructor(content: string);
     protected static normalizeContent(content: string): string;
+    protected static buildCodeFenceMask(lines: string[]): boolean[];
+    private static getFenceMarker;
+    private static isClosingFence;
     parseSpec(name: string): Spec;
     parseChange(name: string): Change;
     protected parseSections(): Section[];

package/dist/core/parsers/markdown-parser.js

@@ -1,14 +1,51 @@
 export class MarkdownParser {
     lines;
+    codeFenceLineMask;
     currentLine;
     constructor(content) {
         const normalized = MarkdownParser.normalizeContent(content);
         this.lines = normalized.split('\n');
+        this.codeFenceLineMask = MarkdownParser.buildCodeFenceMask(this.lines);
         this.currentLine = 0;
     }
     static normalizeContent(content) {
         return content.replace(/\r\n?/g, '\n');
     }
+    static buildCodeFenceMask(lines) {
+        const mask = new Array(lines.length).fill(false);
+        let activeFence = null;
+        for (let i = 0; i < lines.length; i++) {
+            const fence = MarkdownParser.getFenceMarker(lines[i]);
+            if (!activeFence) {
+                if (fence) {
+                    activeFence = fence;
+                    mask[i] = true;
+                }
+                continue;
+            }
+            mask[i] = true;
+            if (MarkdownParser.isClosingFence(lines[i], activeFence)) {
+                activeFence = null;
+            }
+        }
+        return mask;
+    }
+    static getFenceMarker(line) {
+        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+        if (!fenceMatch) {
+            return null;
+        }
+        return {
+            marker: fenceMatch[1][0],
+            length: fenceMatch[1].length,
+        };
+    }
+    static isClosingFence(line, activeFence) {
+        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
+        return Boolean(fenceMatch &&
+            fenceMatch[1][0] === activeFence.marker &&
+            fenceMatch[1].length >= activeFence.length);
+    }
     parseSpec(name) {
         const sections = this.parseSections();
         const purpose = this.findSection(sections, 'Purpose')?.content || '';
@@ -57,6 +94,9 @@ export class MarkdownParser {
         const stack = [];
         for (let i = 0; i < this.lines.length; i++) {
             const line = this.lines[i];
+            if (this.codeFenceLineMask[i]) {
+                continue;
+            }
             const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
             if (headerMatch) {
                 const level = headerMatch[1].length;
@@ -86,7 +126,7 @@ export class MarkdownParser {
         const contentLines = [];
         for (let i = startLine; i < this.lines.length; i++) {
             const line = this.lines[i];
-            const headerMatch = line.match(/^(#{1,6})\s+/);
+            const headerMatch = this.codeFenceLineMask[i] ? null : line.match(/^(#{1,6})\s+/);
             if (headerMatch && headerMatch[1].length <= currentLevel) {
                 break;
             }

package/dist/core/parsers/spec-structure.d.ts

@@ -0,0 +1,9 @@
+export interface MainSpecStructureIssue {
+    kind: 'delta-header' | 'requirement-outside-requirements';
+    line: number;
+    header: string;
+    message: string;
+}
+export declare function findMainSpecStructureIssues(content: string): MainSpecStructureIssue[];
+export declare function stripFencedCodeBlocksPreservingLines(content: string): string;
+//# sourceMappingURL=spec-structure.d.ts.map

package/dist/core/parsers/spec-structure.js

@@ -0,0 +1,88 @@
+const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
+const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
+const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+export function findMainSpecStructureIssues(content) {
+    const normalized = content.replace(/\r\n?/g, '\n');
+    const stripped = stripFencedCodeBlocksPreservingLines(normalized);
+    const lines = stripped.split('\n');
+    const issues = [];
+    const requirementsHeaderIndex = lines.findIndex(line => REQUIREMENTS_SECTION_HEADER.test(line));
+    let requirementsEndIndex = lines.length;
+    if (requirementsHeaderIndex !== -1) {
+        for (let i = requirementsHeaderIndex + 1; i < lines.length; i++) {
+            if (TOP_LEVEL_SECTION_HEADER.test(lines[i])) {
+                requirementsEndIndex = i;
+                break;
+            }
+        }
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (DELTA_HEADER.test(line)) {
+            issues.push({
+                kind: 'delta-header',
+                line: i + 1,
+                header: trimmed,
+                message: `Main spec contains delta header "${trimmed}". ` +
+                    'Delta headers are only valid inside openspec/changes/<name>/specs/<capability>/spec.md ' +
+                    'and truncate the parsed ## Requirements section.',
+            });
+            continue;
+        }
+        const requirementMatch = line.match(REQUIREMENT_HEADER);
+        if (!requirementMatch) {
+            continue;
+        }
+        const insideRequirements = requirementsHeaderIndex !== -1 &&
+            i > requirementsHeaderIndex &&
+            i < requirementsEndIndex;
+        if (!insideRequirements) {
+            issues.push({
+                kind: 'requirement-outside-requirements',
+                line: i + 1,
+                header: trimmed,
+                message: `Requirement header "${trimmed}" appears outside the main ## Requirements section. ` +
+                    'Main specs only parse requirements inside that section, so this requirement is currently invisible to validate, list, and archive.',
+            });
+        }
+    }
+    return issues;
+}
+export function stripFencedCodeBlocksPreservingLines(content) {
+    const lines = content.split('\n');
+    const output = [];
+    let activeFence = null;
+    for (const line of lines) {
+        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})(.*)$/);
+        if (!activeFence) {
+            if (fenceMatch) {
+                activeFence = {
+                    marker: fenceMatch[1][0],
+                    length: fenceMatch[1].length,
+                };
+                output.push('');
+            }
+            else {
+                output.push(line);
+            }
+            continue;
+        }
+        output.push('');
+        if (isClosingFence(line, activeFence)) {
+            activeFence = null;
+        }
+    }
+    return output.join('\n');
+}
+function isClosingFence(line, activeFence) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
+    return Boolean(fenceMatch &&
+        fenceMatch[1][0] === activeFence.marker &&
+        fenceMatch[1].length >= activeFence.length);
+}
+//# sourceMappingURL=spec-structure.js.map

package/dist/core/specs-apply.js

@@ -8,6 +8,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { Validator } from './validation/validator.js';
 // -----------------------------------------------------------------------------
 // Public API
@@ -153,6 +154,13 @@ export async function buildUpdatedSpec(update, changeName) {
         isNewSpec = true;
         targetContent = buildSpecSkeleton(specName, changeName);
     }
+    const structureIssues = findMainSpecStructureIssues(targetContent);
+    if (structureIssues.length > 0) {
+        const details = structureIssues
+            .map(issue => `line ${issue.line}: ${issue.message}`)
+            .join('\n');
+        throw new Error(`${specName}: target spec is structurally invalid and cannot be updated until fixed:\n${details}`);
+    }
     // Extract requirements section and build name->block map
     const parts = extractRequirementsSection(targetContent);
     const nameToBlock = new Map();

package/dist/core/templates/workflows/apply-change.js

@@ -32,7 +32,7 @@ export function getApplyChangeSkillTemplate() {
    \`\`\`
 
    This returns:
-   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
    - Progress (total, complete, remaining)
    - Task list with status
    - Dynamic instruction based on current state
@@ -44,7 +44,7 @@ export function getApplyChangeSkillTemplate() {
 
 4. **Read context files**
 
-   Read the files listed in \`contextFiles\` from the apply instructions output.
+   Read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
    - **spec-driven**: proposal, specs, design, tasks
    - Other schemas: follow the contextFiles from CLI output
@@ -188,7 +188,7 @@ export function getOpsxApplyCommandTemplate() {
    \`\`\`
 
    This returns:
-   - Context file paths (varies by schema)
+   - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema)
    - Progress (total, complete, remaining)
    - Task list with status
    - Dynamic instruction based on current state
@@ -200,7 +200,7 @@ export function getOpsxApplyCommandTemplate() {
 
 4. **Read context files**
 
-   Read the files listed in \`contextFiles\` from the apply instructions output.
+   Read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
    - **spec-driven**: proposal, specs, design, tasks
    - Other schemas: follow the contextFiles from CLI output

package/dist/core/templates/workflows/verify-change.js

@@ -32,7 +32,7 @@ export function getVerifyChangeSkillTemplate() {
    openspec instructions apply --change "<name>" --json
    \`\`\`
 
-   This returns the change directory and context files. Read all available artifacts from \`contextFiles\`.
+   This returns the change directory and \`contextFiles\` (artifact ID -> array of concrete file paths). Read all available artifacts from \`contextFiles\`.
 
 4. **Initialize verification report structure**
 
@@ -46,7 +46,7 @@ export function getVerifyChangeSkillTemplate() {
 5. **Verify Completeness**
 
    **Task Completion**:
-   - If tasks.md exists in contextFiles, read it
+   - If \`contextFiles.tasks\` exists, read every file path in it
    - Parse checkboxes: \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
    - Count complete vs total tasks
    - If incomplete tasks exist:
@@ -85,7 +85,7 @@ export function getVerifyChangeSkillTemplate() {
 7. **Verify Coherence**
 
    **Design Adherence**:
-   - If design.md exists in contextFiles:
+   - If \`contextFiles.design\` exists:
      - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
      - Verify implementation follows those decisions
      - If contradiction detected:
@@ -200,7 +200,7 @@ export function getOpsxVerifyCommandTemplate() {
    openspec instructions apply --change "<name>" --json
    \`\`\`
 
-   This returns the change directory and context files. Read all available artifacts from \`contextFiles\`.
+   This returns the change directory and \`contextFiles\` (artifact ID -> array of concrete file paths). Read all available artifacts from \`contextFiles\`.
 
 4. **Initialize verification report structure**
 
@@ -214,7 +214,7 @@ export function getOpsxVerifyCommandTemplate() {
 5. **Verify Completeness**
 
    **Task Completion**:
-   - If tasks.md exists in contextFiles, read it
+   - If \`contextFiles.tasks\` exists, read every file path in it
    - Parse checkboxes: \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
    - Count complete vs total tasks
    - If incomplete tasks exist:
@@ -253,7 +253,7 @@ export function getOpsxVerifyCommandTemplate() {
 7. **Verify Coherence**
 
    **Design Adherence**:
-   - If design.md exists in contextFiles:
+   - If \`contextFiles.design\` exists:
      - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
      - Verify implementation follows those decisions
      - If contradiction detected:

package/dist/core/validation/validator.js

@@ -5,6 +5,7 @@ import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
 import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
+import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 export class Validator {
     strictMode;
@@ -270,6 +271,14 @@ export class Validator {
     }
     applySpecRules(spec, content) {
         const issues = [];
+        for (const structuralIssue of findMainSpecStructureIssues(content)) {
+            issues.push({
+                level: 'ERROR',
+                path: 'file',
+                line: structuralIssue.line,
+                message: structuralIssue.message,
+            });
+        }
         if (spec.overview.length < MIN_PURPOSE_LENGTH) {
             issues.push({
                 level: 'WARNING',

package/dist/telemetry/config.d.ts

@@ -1,3 +1,5 @@
+export declare const CONFIG_DIR_NAME = "openspec";
+export declare const CONFIG_FILE_NAME = "config.json";
 export interface TelemetryConfig {
     anonymousId?: string;
     noticeSeen?: boolean;
@@ -8,7 +10,11 @@ export interface GlobalConfig {
 }
 /**
  * Get the path to the global config file.
- * Uses ~/.config/openspec/config.json on all platforms.
+ * Follows XDG Base Directory Specification and platform conventions.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
  */
 export declare function getConfigPath(): string;
 /**

package/dist/telemetry/config.js

@@ -1,17 +1,96 @@
 /**
  * Global configuration for telemetry state.
- * Stores anonymous ID and notice-seen flag in ~/.config/openspec/config.json
+ * Stores anonymous ID and notice-seen flag in the platform-appropriate config directory.
  */
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
+import { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, getGlobalConfigDir, } from '../core/global-config.js';
+// Constants
+export const CONFIG_DIR_NAME = GLOBAL_CONFIG_DIR_NAME;
+export const CONFIG_FILE_NAME = GLOBAL_CONFIG_FILE_NAME;
+function getConfigDir() {
+    return getGlobalConfigDir();
+}
+function getLegacyConfigPath() {
+    return path.join(os.homedir(), '.config', CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+}
+async function readConfigFile(configPath) {
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        return { status: 'ok', config: JSON.parse(content) };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { status: 'missing' };
+        }
+        // If parse fails or another read error occurs, ignore the file.
+        return { status: 'invalid', config: {} };
+    }
+}
+async function writeConfigFile(configPath, config) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+function hasMissingTelemetryFields(config) {
+    const telemetry = config.telemetry;
+    return (!telemetry ||
+        telemetry.anonymousId === undefined ||
+        telemetry.noticeSeen === undefined);
+}
+function mergeLegacyTelemetry(config, legacyConfig) {
+    const legacyTelemetry = legacyConfig.telemetry;
+    if (!legacyTelemetry) {
+        return undefined;
+    }
+    const currentTelemetry = config.telemetry ?? {};
+    const shouldMigrate = (currentTelemetry.anonymousId === undefined && legacyTelemetry.anonymousId !== undefined) ||
+        (currentTelemetry.noticeSeen === undefined && legacyTelemetry.noticeSeen !== undefined);
+    if (!shouldMigrate) {
+        return undefined;
+    }
+    return {
+        ...config,
+        telemetry: {
+            ...legacyTelemetry,
+            ...currentTelemetry,
+        },
+    };
+}
+async function migrateLegacyTelemetryConfig(configPath, config, persist) {
+    const legacyConfigPath = getLegacyConfigPath();
+    if (path.resolve(configPath) === path.resolve(legacyConfigPath) || !hasMissingTelemetryFields(config)) {
+        return config;
+    }
+    const legacyRead = await readConfigFile(legacyConfigPath);
+    if (legacyRead.status !== 'ok') {
+        return config;
+    }
+    const migrated = mergeLegacyTelemetry(config, legacyRead.config);
+    if (!migrated) {
+        return config;
+    }
+    if (persist) {
+        try {
+            await writeConfigFile(configPath, migrated);
+        }
+        catch {
+            // Preserve telemetry for this run even if the one-time migration cannot be persisted.
+        }
+    }
+    return migrated;
+}
 /**
  * Get the path to the global config file.
- * Uses ~/.config/openspec/config.json on all platforms.
+ * Follows XDG Base Directory Specification and platform conventions.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
  */
 export function getConfigPath() {
-    const configDir = path.join(os.homedir(), '.config', 'openspec');
-    return path.join(configDir, 'config.json');
+    const configDir = getConfigDir();
+    return path.join(configDir, CONFIG_FILE_NAME);
 }
 /**
  * Read the global config file.
@@ -19,17 +98,9 @@ export function getConfigPath() {
  */
 export async function readConfig() {
     const configPath = getConfigPath();
-    try {
-        const content = await fs.readFile(configPath, 'utf-8');
-        return JSON.parse(content);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return {};
-        }
-        // If parse fails or other error, return empty config
-        return {};
-    }
+    const read = await readConfigFile(configPath);
+    const config = read.status === 'ok' ? read.config : {};
+    return migrateLegacyTelemetryConfig(configPath, config, read.status !== 'invalid');
 }
 /**
  * Write to the global config file.
@@ -37,9 +108,6 @@ export async function readConfig() {
  */
 export async function writeConfig(updates) {
     const configPath = getConfigPath();
-    const configDir = path.dirname(configPath);
-    // Ensure directory exists
-    await fs.mkdir(configDir, { recursive: true });
     // Read existing config and merge
     const existing = await readConfig();
     const merged = { ...existing, ...updates };
@@ -47,7 +115,7 @@ export async function writeConfig(updates) {
     if (updates.telemetry && existing.telemetry) {
         merged.telemetry = { ...existing.telemetry, ...updates.telemetry };
     }
-    await fs.writeFile(configPath, JSON.stringify(merged, null, 2) + '\n');
+    await writeConfigFile(configPath, merged);
 }
 /**
  * Get the telemetry config section.

package/dist/telemetry/index.js

@@ -16,8 +16,21 @@ import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
 const POSTHOG_API_KEY = 'phc_Hthu8YvaIJ9QaFKyTG4TbVwkbd5ktcAFzVTKeMmoW2g';
 // Using reverse proxy to avoid ad blockers and keep traffic on our domain
 const POSTHOG_HOST = 'https://edge.openspec.dev';
+const TELEMETRY_REQUEST_TIMEOUT_MS = 1000;
 let posthogClient = null;
 let anonymousId = null;
+async function safeTelemetryFetch(url, options) {
+    try {
+        const response = await fetch(url, options);
+        if (response.ok) {
+            return response;
+        }
+    }
+    catch {
+        // Silent failure - telemetry should never surface network noise
+    }
+    return new Response(null, { status: 204 });
+}
 /**
  * Check if telemetry is enabled.
  *
@@ -71,6 +84,12 @@ function getClient() {
             host: POSTHOG_HOST,
             flushAt: 1, // Send immediately, don't batch
             flushInterval: 0, // No timer-based flushing
+            fetchRetryCount: 0,
+            requestTimeout: TELEMETRY_REQUEST_TIMEOUT_MS,
+            preloadFeatureFlags: false,
+            disableRemoteConfig: true,
+            disableSurveys: true,
+            fetch: safeTelemetryFetch,
         });
     }
     return posthogClient;

package/dist/utils/file-system.d.ts

@@ -4,6 +4,11 @@ export declare class FileSystemUtils {
      * Essential for cross-platform compatibility with glob libraries like fast-glob.
      */
     static toPosixPath(p: string): string;
+    /**
+     * 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;
     private static isWindowsBasePath;
     private static normalizeSegments;
     static joinPath(basePath: string, ...segments: string[]): string;

package/dist/utils/file-system.js

@@ -1,5 +1,7 @@
-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, markerIndex, markerLength) {
     let leftIndex = markerIndex - 1;
     while (leftIndex >= 0 && content[leftIndex] !== '\n') {
@@ -37,6 +39,24 @@ export class FileSystemUtils {
     static toPosixPath(p) {
         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) {
+        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);
+            }
+        }
+    }
     static isWindowsBasePath(basePath) {
         return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",