@fission-ai/openspec 1.2.0 → 1.3.1

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/bulk-archive-change.js

@@ -77,7 +77,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    \`\`\`
-   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
@@ -323,7 +323,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    \`\`\`
-   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |

package/dist/core/templates/workflows/explore.js

@@ -49,10 +49,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│   ┌────────┐         ┌────────┐        │
-│   │ State  │────────▶│ State  │        │
-│   │   A    │         │   B    │        │
-│   └────────┘         └────────┘        │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -107,14 +107,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-   | Insight Type | Where to Capture |
-   |--------------|------------------|
-   | New requirement discovered | \`specs/<capability>/spec.md\` |
-   | Requirement changed | \`specs/<capability>/spec.md\` |
-   | Design decision made | \`design.md\` |
-   | Scope changed | \`proposal.md\` |
-   | New work identified | \`tasks.md\` |
-   | Assumption invalidated | Relevant artifact |
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | \`specs/<capability>/spec.md\` |
+    | Requirement changed        | \`specs/<capability>/spec.md\` |
+    | Design decision made       | \`design.md\`                  |
+    | Scope changed              | \`proposal.md\`                |
+    | New work identified        | \`tasks.md\`                   |
+    | Assumption invalidated     | Relevant artifact              |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"
@@ -220,7 +220,7 @@ User: A CLI tool that tracks local dev environments
 You: That changes everything.
 
      ┌─────────────────────────────────────────────────┐
-     │         CLI TOOL DATA STORAGE                  │
+     │          CLI TOOL DATA STORAGE                  │
      └─────────────────────────────────────────────────┘
 
      Key constraints:
@@ -344,10 +344,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│   ┌────────┐         ┌────────┐        │
-│   │ State  │────────▶│ State  │        │
-│   │   A    │         │   B    │        │
-│   └────────┘         └────────┘        │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -404,14 +404,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-   | Insight Type | Where to Capture |
-   |--------------|------------------|
-   | New requirement discovered | \`specs/<capability>/spec.md\` |
-   | Requirement changed | \`specs/<capability>/spec.md\` |
-   | Design decision made | \`design.md\` |
-   | Scope changed | \`proposal.md\` |
-   | New work identified | \`tasks.md\` |
-   | Assumption invalidated | Relevant artifact |
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | \`specs/<capability>/spec.md\` |
+    | Requirement changed        | \`specs/<capability>/spec.md\` |
+    | Design decision made       | \`design.md\`                  |
+    | Scope changed              | \`proposal.md\`                |
+    | New work identified        | \`tasks.md\`                   |
+    | Assumption invalidated     | Relevant artifact              |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"

package/dist/core/templates/workflows/onboard.js

@@ -468,21 +468,21 @@ This same rhythm works for any size change—a small fix or a major feature.
 
 **Core workflow:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:propose\` | Create a change and generate all artifacts |
-| \`/opsx:explore\` | Think through problems before/during work |
-| \`/opsx:apply\` | Implement tasks from a change |
-| \`/opsx:archive\` | Archive a completed change |
+ | Command           | What it does                               |
+ |-------------------|--------------------------------------------|
+ | \`/opsx:propose\` | Create a change and generate all artifacts |
+ | \`/opsx:explore\` | Think through problems before/during work  |
+ | \`/opsx:apply\`   | Implement tasks from a change              |
+ | \`/opsx:archive\` | Archive a completed change                 |
 
 **Additional commands:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:new\` | Start a new change, step through artifacts one at a time |
-| \`/opsx:continue\` | Continue working on an existing change |
-| \`/opsx:ff\` | Fast-forward: create all artifacts at once |
-| \`/opsx:verify\` | Verify implementation matches artifacts |
+ | Command            | What it does                                             |
+ |--------------------|----------------------------------------------------------|
+ | \`/opsx:new\`      | Start a new change, step through artifacts one at a time |
+ | \`/opsx:continue\` | Continue working on an existing change                   |
+ | \`/opsx:ff\`       | Fast-forward: create all artifacts at once               |
+ | \`/opsx:verify\`   | Verify implementation matches artifacts                  |
 
 ---
 
@@ -520,21 +520,21 @@ If the user says they just want to see the commands or skip the tutorial:
 
 **Core workflow:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:propose <name>\` | Create a change and generate all artifacts |
-| \`/opsx:explore\` | Think through problems (no code changes) |
-| \`/opsx:apply <name>\` | Implement tasks |
-| \`/opsx:archive <name>\` | Archive when done |
+ | Command                  | What it does                               |
+ |--------------------------|--------------------------------------------|
+ | \`/opsx:propose <name>\` | Create a change and generate all artifacts |
+ | \`/opsx:explore\`        | Think through problems (no code changes)   |
+ | \`/opsx:apply <name>\`   | Implement tasks                            |
+ | \`/opsx:archive <name>\` | Archive when done                          |
 
 **Additional commands:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:new <name>\` | Start a new change, step by step |
-| \`/opsx:continue <name>\` | Continue an existing change |
-| \`/opsx:ff <name>\` | Fast-forward: all artifacts at once |
-| \`/opsx:verify <name>\` | Verify implementation |
+ | Command                   | What it does                        |
+ |---------------------------|-------------------------------------|
+ | \`/opsx:new <name>\`      | Start a new change, step by step    |
+ | \`/opsx:continue <name>\` | Continue an existing change         |
+ | \`/opsx:ff <name>\`       | Fast-forward: all artifacts at once |
+ | \`/opsx:verify <name>\`   | Verify implementation               |
 
 Try \`/opsx:propose\` to start your first change.
 \`\`\`

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/update.js

@@ -129,7 +129,7 @@ export class UpdateCommand {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
@@ -504,7 +504,7 @@ export class UpdateCommand {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }

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.