@fission-ai/openspec 1.12.0 → 1.13.1

package/README.md

@@ -141,7 +141,7 @@ openspec init
 
 Now talk to your AI:
 
-- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. ([Explore guide](docs/explore.md))
 - **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
 
 Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
@@ -224,21 +224,9 @@ openspec update
 
 ## Contributing
 
-**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+Open a discussion (for core design changes) or an issue before you open a PR, and link the issue or discussion from the PR. New features, significant refactors, and architectural changes need an OpenSpec change proposal first.
 
-**Larger changes** — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
-
-When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
-
-**AI-generated code is welcome** — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
-
-### Development
-
-- Install dependencies: `pnpm install`
-- Build: `pnpm run build`
-- Test: `pnpm test`
-- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
-- Conventional commits (one-line): `type(scope): subject`
+→ **[CONTRIBUTING.md](CONTRIBUTING.md)**: the full process, from first issue to merged PR
 
 ## Other
 

package/dist/commands/change.js

@@ -7,6 +7,7 @@ import { VALIDATION_MESSAGES } from '../core/validation/constants.js';
 import { ChangeParser } from '../core/parsers/change-parser.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds } from '../utils/item-discovery.js';
+import { describeNestedChange, findNestedChangesIn, } from '../utils/nested-change.js';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
@@ -102,6 +103,13 @@ export class ChangeCommand {
                 .then((stats) => stats.isDirectory())
                 .catch(() => false);
             if (isChangeDirectory) {
+                // A folder holding nested change directories has no proposal of its
+                // own and never will; pointing at `status --change` would send the
+                // user down a second dead end (#1846).
+                const nested = await findNestedChangesIn(changesPath, changeName);
+                if (nested) {
+                    throw new Error(describeNestedChange(nested));
+                }
                 throw new Error(`Change "${changeName}" has no proposal.md yet. ` +
                     `Run "openspec status --change ${changeName}" to see which artifact comes next.`);
             }
@@ -496,7 +504,10 @@ export class ChangeCommand {
     }
     extractTitle(content, changeName) {
         const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/im);
-        return match ? match[1].trim() : changeName;
+        const title = match?.[1].trim();
+        // The packaged template opens every proposal with a bare `# Proposal`,
+        // which names the document rather than the change.
+        return title && title.toLowerCase() !== 'proposal' ? title : changeName;
     }
     printNextSteps(issues = []) {
         const bullets = [];

package/dist/commands/config.d.ts

@@ -1,6 +1,15 @@
 import { Command } from 'commander';
 import { GlobalConfig } from '../core/global-config.js';
 import type { Profile, Delivery } from '../core/global-config.js';
+/**
+ * Splits an EDITOR or VISUAL value into a program and its arguments without
+ * running a shell, so `;`, `|`, `$VAR`, `~` and backticks are plain characters.
+ * Double quotes group words. On POSIX, single quotes group words too and a
+ * backslash escapes the next character (inside double quotes only `"` and `\`).
+ * On Windows a backslash is a path separator and a single quote is a plain
+ * character. Returns null when a quote is left open.
+ */
+export declare function splitEditorCommand(value: string, platform?: NodeJS.Platform): string[] | null;
 interface ProfileState {
     profile: Profile;
     delivery: Delivery;

package/dist/commands/config.js

@@ -1,13 +1,148 @@
-import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
 import * as path from 'node:path';
-import { getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, } from '../core/global-config.js';
+import { getGlobalConfigPath, getGlobalConfig, isConfigRootObject, isGlobalConfigUnreadable, saveGlobalConfig, } from '../core/global-config.js';
 import { getNestedValue, setNestedValue, deleteNestedValue, coerceValue, formatValueYaml, validateConfigKeyPath, hasUnsafeKeySegment, validateConfig, DEFAULT_CONFIG, } from '../core/config-schema.js';
 import { CORE_WORKFLOWS, ALL_WORKFLOWS, getProfileWorkflows } from '../core/profiles.js';
 import { OPENSPEC_DIR_NAME } from '../core/config.js';
 import { hasProjectConfigDrift } from '../core/profile-sync-drift.js';
 import { UpdateCommand } from '../core/update.js';
 import { asErrorMessage, isPromptCancellationError } from './shared-output.js';
+// cross-spawn finds `.cmd` shims such as `code.cmd` on Windows and escapes each
+// argument for cmd.exe; elsewhere it is plain spawn. Loaded lazily so other
+// commands skip its module graph.
+let cachedSpawn;
+function loadSpawn() {
+    if (cachedSpawn === undefined) {
+        cachedSpawn = createRequire(import.meta.url)('cross-spawn');
+    }
+    return cachedSpawn;
+}
+/**
+ * Splits an EDITOR or VISUAL value into a program and its arguments without
+ * running a shell, so `;`, `|`, `$VAR`, `~` and backticks are plain characters.
+ * Double quotes group words. On POSIX, single quotes group words too and a
+ * backslash escapes the next character (inside double quotes only `"` and `\`).
+ * On Windows a backslash is a path separator and a single quote is a plain
+ * character. Returns null when a quote is left open.
+ */
+export function splitEditorCommand(value, platform = process.platform) {
+    const posix = platform !== 'win32';
+    const words = [];
+    let word = '';
+    let inWord = false;
+    let quote = null;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (quote === "'") {
+            if (ch === "'")
+                quote = null;
+            else
+                word += ch;
+            continue;
+        }
+        if (posix && ch === '\\' && i + 1 < value.length) {
+            const next = value[i + 1];
+            if (quote === '"' && next !== '"' && next !== '\\') {
+                word += ch;
+            }
+            else {
+                word += next;
+                i++;
+            }
+            inWord = true;
+            continue;
+        }
+        if (quote === '"') {
+            if (ch === '"')
+                quote = null;
+            else
+                word += ch;
+            continue;
+        }
+        if (ch === '"' || (posix && ch === "'")) {
+            quote = ch;
+            inWord = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (inWord)
+                words.push(word);
+            word = '';
+            inWord = false;
+            continue;
+        }
+        word += ch;
+        inWord = true;
+    }
+    if (quote)
+        return null;
+    if (inWord)
+        words.push(word);
+    return words;
+}
+/**
+ * Starts the user's editor on `filePath`, never through a shell.
+ *
+ * EDITOR and VISUAL hold a command line, not a program name: `code --wait`
+ * and `"/path with spaces/subl" -w` are both ordinary values, so the value is
+ * split into words and the file path is appended as its own argument. A value
+ * that is itself the absolute path of an existing file is run as-is, so an
+ * unquoted editor path with spaces keeps working.
+ */
+function spawnEditor(editor, filePath) {
+    const words = path.isAbsolute(editor) && fs.existsSync(editor) ? [editor] : splitEditorCommand(editor);
+    if (words === null) {
+        throw new Error('the value has an unterminated quote');
+    }
+    if (words.length === 0) {
+        throw new Error('the value is blank');
+    }
+    const [program, ...args] = words;
+    return loadSpawn()(program, [...args, filePath], { stdio: 'inherit', shell: false });
+}
+/** Runs the editor on `filePath` and resolves once it has closed or failed to start. */
+function runEditor(editor, filePath) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawnEditor(editor, filePath);
+            child.once('error', (error) => resolve({ error }));
+            child.once('close', (code, signal) => resolve({ code, signal }));
+        }
+        catch (error) {
+            resolve({ error: error instanceof Error ? error : new Error(String(error)) });
+        }
+    });
+}
+function reportEditorFailure(editor, outcome) {
+    if ('error' in outcome) {
+        console.error(`Error: Could not start editor "${editor}": ${outcome.error.message}`);
+    }
+    else if (outcome.signal) {
+        console.error(`Error: Editor "${editor}" was terminated by ${outcome.signal}`);
+    }
+    else {
+        console.error(`Error: Editor "${editor}" exited with code ${outcome.code}`);
+    }
+    // Only a missing program earns the hint: EACCES or EPERM means it exists.
+    if ('error' in outcome && outcome.error.code === 'ENOENT') {
+        console.error('Set EDITOR or VISUAL to an installed editor command, for example: export EDITOR="code --wait"');
+    }
+}
+/**
+ * A config file that exists but cannot be parsed is still the user's file:
+ * getGlobalConfig() reads it as defaults, and saving those back would erase
+ * every setting in it. Reports the fix instead, and returns true when it did.
+ */
+function refuseUnreadableConfig() {
+    if (!isGlobalConfigUnreadable()) {
+        return false;
+    }
+    console.error(`Error: ${getGlobalConfigPath()} could not be parsed, so it was left unchanged.`);
+    console.error('Fix it with "openspec config edit", or reset it with "openspec config reset --all".');
+    process.exitCode = 1;
+    return true;
+}
 export const WORKFLOW_PROMPT_META = {
     propose: {
         name: 'Propose change',
@@ -187,7 +322,12 @@ export function registerConfigCommand(program) {
             let rawConfig = {};
             try {
                 if (fs.existsSync(configPath)) {
-                    rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                    // A non-object root holds no explicit settings, and reading a key
+                    // off `null` would crash this read-only command.
+                    if (isConfigRootObject(parsed)) {
+                        rawConfig = parsed;
+                    }
                 }
             }
             catch {
@@ -250,6 +390,9 @@ export function registerConfigCommand(program) {
             process.exitCode = 1;
             return;
         }
+        if (refuseUnreadableConfig()) {
+            return;
+        }
         const config = getGlobalConfig();
         const coercedValue = coerceValue(value, options.string || false);
         // Create a copy to validate before saving
@@ -273,6 +416,9 @@ export function registerConfigCommand(program) {
         .command('unset <key>')
         .description('Remove a key (revert to default)')
         .action((key) => {
+        if (refuseUnreadableConfig()) {
+            return;
+        }
         const config = getGlobalConfig();
         const existed = deleteNestedValue(config, key);
         if (existed) {
@@ -318,7 +464,8 @@ export function registerConfigCommand(program) {
                 return;
             }
         }
-        saveGlobalConfig({ ...DEFAULT_CONFIG });
+        // A reset is the one write meant to replace a file that cannot be parsed.
+        saveGlobalConfig({ ...DEFAULT_CONFIG }, { replaceUnreadable: true });
         console.log('Configuration reset to defaults');
     });
     // config edit
@@ -339,24 +486,13 @@ export function registerConfigCommand(program) {
         if (!fs.existsSync(configPath)) {
             saveGlobalConfig({ ...DEFAULT_CONFIG });
         }
-        // Spawn editor and wait for it to close
-        // Avoid shell parsing to correctly handle paths with spaces in both
-        // the editor path and config path
-        const child = spawn(editor, [configPath], {
-            stdio: 'inherit',
-            shell: false,
-        });
-        await new Promise((resolve, reject) => {
-            child.on('close', (code) => {
-                if (code === 0) {
-                    resolve();
-                }
-                else {
-                    reject(new Error(`Editor exited with code ${code}`));
-                }
-            });
-            child.on('error', reject);
-        });
+        // Wait for the editor to close; a failure is reported, never thrown.
+        const outcome = await runEditor(editor, configPath);
+        if ('error' in outcome || outcome.code !== 0) {
+            reportEditorFailure(editor, outcome);
+            process.exitCode = 1;
+            return;
+        }
         try {
             const rawConfig = fs.readFileSync(configPath, 'utf-8');
             const parsedConfig = JSON.parse(rawConfig);
@@ -385,6 +521,9 @@ export function registerConfigCommand(program) {
         .command('profile [preset]')
         .description('Configure workflow profile (interactive picker or preset shortcut)')
         .action(async (preset) => {
+        if (refuseUnreadableConfig()) {
+            return;
+        }
         // Preset shortcut: `openspec config profile core`
         if (preset === 'core') {
             const config = getGlobalConfig();

package/dist/commands/feedback.js

@@ -1,4 +1,4 @@
-import { execSync, execFileSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { createRequire } from 'module';
 import os from 'os';
 const require = createRequire(import.meta.url);
@@ -10,8 +10,10 @@ const TITLE_PREFIX = 'Feedback: ';
  */
 function isGhInstalled() {
     try {
-        const command = process.platform === 'win32' ? 'where gh' : 'which gh';
-        execSync(command, { stdio: 'pipe' });
+        // execFileSync, not execSync: no shell is needed to look a binary up, and
+        // spawning one next to free-form issue text is the shape a future refactor
+        // most easily turns into command injection.
+        execFileSync(process.platform === 'win32' ? 'where' : 'which', ['gh'], { stdio: 'pipe' });
         return true;
     }
     catch {
@@ -23,7 +25,7 @@ function isGhInstalled() {
  */
 function isGhAuthenticated() {
     try {
-        execSync('gh auth status', { stdio: 'pipe' });
+        execFileSync('gh', ['auth', 'status'], { stdio: 'pipe' });
         return true;
     }
     catch {

package/dist/commands/schema.js

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import ora from 'ora';
 import { stringify as stringifyYaml, parseDocument, isMap } from 'yaml';
 import { getSchemaDir, getProjectSchemasDir, getUserSchemasDir, getPackageSchemasDir, isSchemaDir, listSchemas, } from '../core/artifact-graph/resolver.js';
-import { parseSchema, SchemaValidationError } from '../core/artifact-graph/schema.js';
+import { findApplyTracksWarning, parseSchema, SchemaValidationError, } from '../core/artifact-graph/schema.js';
 import { resolveConfigFilePath } from '../core/project-config.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 /**
@@ -158,12 +158,18 @@ function validateSchema(schemaDir, verbose = false) {
             });
         }
     }
-    // Dependency graph validation is already done by parseSchema
-    // (it throws on cycles and invalid references)
+    // Dependency graph validation is already done by parseSchema (it throws on
+    // cycles, invalid references, and an unknown apply.requires id)
     if (verbose) {
         console.log('  Dependency graph validation passed (via parseSchema)');
     }
-    return { valid: issues.length === 0, issues };
+    // An apply.tracks value that matches no generates value exactly still loads
+    // (apply reads the path as written), so it is a warning, not an error.
+    const tracksWarning = findApplyTracksWarning(schema);
+    if (tracksWarning) {
+        issues.push({ level: 'warning', path: 'apply.tracks', message: tracksWarning });
+    }
+    return { valid: !issues.some((issue) => issue.level === 'error'), issues };
 }
 /**
  * Validate schema name format (kebab-case).
@@ -590,6 +596,9 @@ export function registerSchemaCommand(program) {
             else {
                 if (result.valid) {
                     console.log(`✓ Schema '${name}' is valid`);
+                    for (const issue of result.issues) {
+                        console.log(`  ${issue.level}: ${issue.message}`);
+                    }
                 }
                 else {
                     console.log(`✗ Schema '${name}' has errors:`);
@@ -1201,11 +1210,17 @@ export function registerSchemaCommand(program) {
 }
 /**
  * Create default template content for an artifact.
+ *
+ * Every template opens with a top-level heading so the artifact it produces is
+ * a well-formed markdown document rather than a file whose first line is a
+ * section header (markdownlint MD041, #1138).
  */
 function createDefaultTemplate(artifactId) {
     switch (artifactId) {
         case 'proposal':
-            return `## Why
+            return `# Proposal
+
+## Why
 
 <!-- Describe the motivation for this change -->
 
@@ -1226,7 +1241,9 @@ function createDefaultTemplate(artifactId) {
 <!-- Describe the impact on existing functionality -->
 `;
         case 'specs':
-            return `## ADDED Requirements
+            return `# Spec Delta
+
+## ADDED Requirements
 
 ### Requirement: Example requirement
 
@@ -1237,7 +1254,9 @@ Description of the requirement.
 - **THEN** some outcome
 `;
         case 'design':
-            return `## Context
+            return `# Design
+
+## Context
 
 <!-- Background and context -->
 
@@ -1263,14 +1282,16 @@ Description and rationale.
 <!-- List risks and trade-offs -->
 `;
         case 'tasks':
-            return `## Implementation Tasks
+            return `# Tasks
+
+## Implementation Tasks
 
 - [ ] Task 1
 - [ ] Task 2
 - [ ] Task 3
 `;
         default:
-            return `## ${artifactId}
+            return `# ${artifactId}
 
 <!-- Add content here -->
 `;

package/dist/commands/store.js

@@ -143,8 +143,11 @@ async function resolveSetupInput(id, options) {
         ...(options.remote !== undefined ? { remote: options.remote } : {}),
     };
 }
-async function prepareSetupInput(input, _options) {
-    return prepareStoreSetup(input);
+async function prepareSetupInput(input, options) {
+    return prepareStoreSetup({
+        ...input,
+        ...(options.initGit !== undefined ? { initGit: options.initGit } : {}),
+    });
 }
 async function confirmSetup(prepared, initGit) {
     const { confirm } = await import('@inquirer/prompts');

package/dist/commands/validate.d.ts

@@ -81,6 +81,13 @@ export declare class ValidateCommand {
     private runInteractiveSelector;
     private printNonInteractiveHint;
     private validateDirectItem;
+    /**
+     * A namespace folder wrapping nested change directories has no deltas of its
+     * own and never will. The usual "add a delta spec" error points the author at
+     * a directory that is not the change, so the nesting is reported instead
+     * (#1846). Returns undefined for every ordinary change.
+     */
+    private nestedChangeReport;
     private validateByType;
     private printReport;
     private printNextSteps;

package/dist/commands/validate.js

@@ -1,5 +1,6 @@
 import ora from 'ora';
 import path from 'path';
+import { describeNestedChange, findNestedChangesIn, NESTED_CHANGE_ISSUE_MARKER, } from '../utils/nested-change.js';
 import { Validator } from '../core/validation/validator.js';
 import { VALIDATION_MESSAGES } from '../core/validation/constants.js';
 import { resolveRootForCommand, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../core/root-selection.js';
@@ -10,6 +11,7 @@ import { nearestMatches } from '../utils/match.js';
 import { promises as fs } from 'fs';
 import { getTaskProgressDetailForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { folderStyleNameProblem } from '../core/id.js';
 /** Findings are a distinct report, not a partial full-v1 items collection. */
 export function projectValidationFindings(full, scope) {
     const itemFindings = full.items.filter(item => item.issues.length > 0);
@@ -204,11 +206,54 @@ export class ValidateCommand {
         }
         await this.validateByType(root, type, itemName, opts);
     }
+    /**
+     * A namespace folder wrapping nested change directories has no deltas of its
+     * own and never will. The usual "add a delta spec" error points the author at
+     * a directory that is not the change, so the nesting is reported instead
+     * (#1846). Returns undefined for every ordinary change.
+     */
+    async nestedChangeReport(root, id) {
+        const nested = await findNestedChangesIn(root.changesDir, id);
+        if (!nested)
+            return undefined;
+        return {
+            valid: false,
+            issues: [{ level: 'ERROR', path: 'file', message: describeNestedChange(nested) }],
+        };
+    }
     async validateByType(root, type, id, opts) {
+        // `--type` skips the membership check above, so the name still has to be
+        // guarded before it is joined onto a directory. `show` already rejects a
+        // traversing id.
+        //
+        // Spec ids are nested (`specs/<area>/<capability>/spec.md`, #1353), so the
+        // guard runs per segment - rejecting the whole id for containing a `/`
+        // would break every nested capability, including the hint that
+        // `validate --specs` prints. Change names are flat, so they keep the
+        // whole-value check.
+        const nameProblem = type === 'change'
+            ? folderStyleNameProblem(id, 'Change name')
+            : (id.split('/').map((segment) => folderStyleNameProblem(segment, 'Spec id')).find(Boolean) ?? null);
+        if (nameProblem) {
+            if (opts.json) {
+                console.log(JSON.stringify({ status: [{ severity: 'error', code: 'invalid_item', message: nameProblem }] }, null, 2));
+            }
+            else {
+                console.error(nameProblem);
+            }
+            process.exitCode = 1;
+            return;
+        }
         const validator = new Validator(opts.strict);
         if (type === 'change') {
             const changeDir = path.join(root.changesDir, id);
             const start = Date.now();
+            const nestedReport = await this.nestedChangeReport(root, id);
+            if (nestedReport) {
+                this.printReport('change', id, nestedReport, Date.now() - start, opts.json, root);
+                process.exitCode = 1;
+                return;
+            }
             const report = await validator.validateChangeDeltaSpecs(changeDir, {
                 mainSpecsDir: root.specsDir,
                 projectRoot: root.path,
@@ -254,7 +299,14 @@ export class ValidateCommand {
         // skip_specs, which must not trigger this.
         const conflictIssue = issues.some(i => i.message.includes(VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_CONFLICT));
         const invalidMarkerIssue = issues.some(i => i.message.includes(VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_INVALID_METADATA));
-        if (type === 'change' && conflictIssue) {
+        // A namespace folder has no deltas to author, so the delta-authoring
+        // bullets below would point at a directory that is not the change (#1846).
+        const nestedIssue = issues.some(i => i.message.includes(NESTED_CHANGE_ISSUE_MARKER));
+        if (type === 'change' && nestedIssue) {
+            bullets.push('- Move each nested change directly under openspec/changes/, folding the namespace into its name');
+            bullets.push('- Only specs may be nested by domain; change directories are always flat');
+        }
+        else if (type === 'change' && conflictIssue) {
             bullets.push('- This change declares skip_specs (no spec deltas): delete the files under specs/, or remove skip_specs from .openspec.yaml if requirements do change');
             bullets.push('- skip_specs is only honored when .openspec.yaml is valid change metadata (schema: <name> naming a known schema is required)');
         }
@@ -318,6 +370,16 @@ export class ValidateCommand {
             queue.push(async () => {
                 const start = Date.now();
                 const changeDir = path.join(root.changesDir, id);
+                const nestedReport = await this.nestedChangeReport(root, id);
+                if (nestedReport) {
+                    return {
+                        id,
+                        type: 'change',
+                        valid: false,
+                        issues: nestedReport.issues,
+                        durationMs: Date.now() - start,
+                    };
+                }
                 const report = await validator.validateChangeDeltaSpecs(changeDir, {
                     mainSpecsDir: root.specsDir,
                     projectRoot: root.path,