@fission-ai/openspec 1.14.3 → 1.16.0

package/README.md

@@ -117,20 +117,20 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.
-
-Install OpenSpec globally:
+Install OpenSpec. On macOS or Linux, in your terminal:
 
 ```bash
-npm install -g @fission-ai/openspec@latest
+curl -fsSL https://openspec.dev/cli/install.sh | sh
 ```
 
-Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:
+On Windows, in PowerShell:
 
-```bash
-brew install openspec
+```powershell
+irm https://openspec.dev/cli/install.ps1 | iex
 ```
 
+Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 22.12.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
+
 Then navigate to your project directory and initialize:
 
 ```bash
@@ -152,7 +152,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](https://openspec.dev/docs/supported-tools) – we support 30+ tools and growing.
 >
-> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](https://openspec.dev/docs/installation).
+> Also works with npm, Homebrew, pnpm, yarn, bun, and Nix. [See installation options](https://openspec.dev/docs/installation).
 
 ## Docs
 
@@ -192,7 +192,9 @@ AI coding assistants are powerful but unpredictable when requirements live only
 
 ## Updating OpenSpec
 
-**Upgrade the package**
+**Upgrade the CLI**
+
+With the standalone install, run `openspec install`. If you installed with npm:
 
 ```bash
 npm install -g @fission-ai/openspec@latest
@@ -220,7 +222,7 @@ openspec update
 
 ## Contributing
 
-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.
+Every change starts as an issue. We discuss it there, and if we agree to pursue it, a maintainer implements the change or invites you to build it with us.
 
 → **[CONTRIBUTING.md](CONTRIBUTING.md)**: the full process, from first issue to merged PR
 

package/dist/cli/index.js

@@ -277,8 +277,29 @@ program
     .command('update [path]')
     .description('Update OpenSpec instruction files')
     .option('--force', 'Force update even when tools are up to date')
+    .option('--dry-run', 'Report what the update would change without writing anything')
+    .option('--json', 'With --dry-run, print the planned changes as JSON')
     .action(async (targetPath = '.', options) => {
     try {
+        if (options?.json && !options?.dryRun) {
+            console.error('--json is only available with --dry-run.');
+            process.exitCode = 1;
+            return;
+        }
+        // A dry run reports the plan and nothing else: no network check, no
+        // upgrade prompt, no output that would break --json.
+        if (options?.dryRun) {
+            const [{ UpdateCommand }, { formatUpdatePlan }] = await Promise.all([
+                import('../core/update.js'),
+                import('../core/update-plan.js'),
+            ]);
+            const plan = await new UpdateCommand({
+                force: options?.force,
+                dryRun: true,
+            }).plan(targetPath);
+            console.log(options?.json ? JSON.stringify(plan, null, 2) : formatUpdatePlan(plan));
+            return;
+        }
         const [{ getInstallDir, isSourceCheckout, getAvailableCliUpdate, shouldOfferUpgrade, displayCliUpdateNote, offerCliUpgrade, rerunUpdateWithUpgradedCli, displayUpgradeCommand, }, { isInteractive }, { UpdateCommand },] = await Promise.all([
             import('../core/version-check.js'),
             import('../utils/interactive.js'),
@@ -333,6 +354,32 @@ program
         else if (latestVersion) {
             displayCliUpdateNote(latestVersion, targetPath);
         }
+        // Once per machine, a package-manager user hears the standalone install
+        // exists. Offered, never pushed; deferred when stderr is not a terminal.
+        const { maybeShowStandaloneTip } = await import('../core/standalone-tip.js');
+        await maybeShowStandaloneTip({ silent: !process.stderr.isTTY });
+    }
+    catch (error) {
+        // The --json dry run follows the agent contract: exactly one JSON
+        // document on stdout, even on failure.
+        // failWithError sets the exit code. Returning instead of process.exit()
+        // lets piped stdout drain - an exit can cut the JSON document short where
+        // pipes are asynchronous (macOS, Windows) - and keeps commander's
+        // postAction telemetry flush, as the upgrade paths above already do.
+        await failWithError(error, {
+            enabled: options?.dryRun && options?.json,
+            payload: { changes: [], notes: [], failures: [] },
+            fallbackCode: 'update_error',
+        });
+    }
+});
+program
+    .command('install [version]')
+    .description('Install the standalone openspec, which runs without Node.js (latest release unless [version] is given)')
+    .action(async (version) => {
+    try {
+        const { installStandalone } = await import('../commands/install-standalone.js');
+        await installStandalone({ version });
     }
     catch (error) {
         await failWithError(error);

package/dist/commands/completion.js

@@ -1,4 +1,5 @@
 import { CompletionFactory } from '../core/completions/factory.js';
+import { zshrcDisplayPath } from '../core/completions/installers/zsh-installer.js';
 import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
 import { detectShell } from '../utils/shell-detection.js';
 import { CompletionProvider } from '../core/completions/completion-provider.js';
@@ -113,7 +114,7 @@ export class CompletionCommand {
                     const configWasUpdated = result.zshrcConfigured || result.bashrcConfigured || result.profileConfigured;
                     if (configWasUpdated) {
                         const configPaths = {
-                            zsh: '~/.zshrc',
+                            zsh: zshrcDisplayPath(),
                             bash: '~/.bashrc',
                             fish: '~/.config/fish/config.fish',
                             powershell: '$PROFILE',
@@ -174,7 +175,8 @@ export class CompletionCommand {
             const { confirm } = await import('@inquirer/prompts');
             // Get shell-specific config file path
             const configPaths = {
-                zsh: '~/.zshrc',
+                // Uninstall also clears a block an older install left in ~/.zshrc.
+                zsh: zshrcDisplayPath() === '~/.zshrc' ? '~/.zshrc' : `${zshrcDisplayPath()} (and ~/.zshrc if an older install wrote there)`,
                 bash: '~/.bashrc',
                 fish: 'Fish configuration', // Fish doesn't modify profile, just removes script file
                 powershell: '$PROFILE',

package/dist/commands/feedback.js

@@ -4,6 +4,7 @@ import os from 'os';
 const require = createRequire(import.meta.url);
 const MAX_TITLE_LENGTH = 72;
 const TITLE_PREFIX = 'Feedback: ';
+const REPRO_PROMPT = '_Not provided — filed with `openspec feedback`. If this is a bug, please add the shortest steps that reproduce it from a fresh project._';
 /**
  * Check if gh CLI is installed and available in PATH
  * Uses platform-appropriate command: 'where' on Windows, 'which' on Unix/macOS
@@ -97,24 +98,37 @@ function formatTitle(message) {
 }
 /**
  * Format the full feedback body
+ *
+ * The headings mirror the bug form's labels (.github/ISSUE_TEMPLATE/bug_report.yml)
+ * so a CLI-filed issue reads like one filed through the form. `gh issue create
+ * --body` cannot fill an issue form, so the repro prompt is spelled out instead
+ * of being left silently empty.
  */
 function formatBody(message, bodyText) {
-    const parts = ['## Summary', '', message];
+    const parts = ['### What happened', '', message];
     if (bodyText) {
-        parts.push('', '## Details', '', bodyText);
+        parts.push('', '### Details', '', bodyText);
     }
+    parts.push('', '### Minimal steps to reproduce', '', REPRO_PROMPT);
     parts.push('', generateMetadata());
     return parts.join('\n');
 }
 /**
  * Generate a pre-filled GitHub issue URL for manual submission
+ *
+ * Opens the bug form itself. The query keys are the form's own field ids, which
+ * is how GitHub prefills an issue form; the fields it leaves empty are the
+ * required ones only the reporter can answer.
  */
-function generateManualSubmissionUrl(title, body) {
-    const repo = 'Fission-AI/OpenSpec';
-    const encodedTitle = encodeURIComponent(title);
-    const encodedBody = encodeURIComponent(body);
-    const encodedLabels = encodeURIComponent('feedback');
-    return `https://github.com/${repo}/issues/new?title=${encodedTitle}&body=${encodedBody}&labels=${encodedLabels}`;
+function generateManualSubmissionUrl(title, message, bodyText) {
+    const params = new URLSearchParams({
+        template: 'bug_report.yml',
+        title,
+        what_happened: bodyText ? `${message}\n\n${bodyText}` : message,
+        version: getVersion(),
+        environment: `${getPlatform()}, Node ${process.version}`,
+    });
+    return `https://github.com/Fission-AI/OpenSpec/issues/new?${params.toString()}`;
 }
 /**
  * Display formatted feedback content for manual submission
@@ -145,7 +159,7 @@ function isMissingLabelError(error) {
  * network, rate limit, ...), so show the same manual-submission path the
  * missing-gh and unauthenticated flows get instead of discarding the text.
  */
-function reportGhFailure(error, title, body) {
+function reportGhFailure(error, title, body, url) {
     // Display the error output from gh CLI
     if (error.stderr) {
         console.error(error.stderr.toString());
@@ -154,9 +168,8 @@ function reportGhFailure(error, title, body) {
         console.error(error.message);
     }
     displayFormattedFeedback(title, body);
-    const manualUrl = generateManualSubmissionUrl(title, body);
     console.log('Please submit your feedback manually:');
-    console.log(manualUrl);
+    console.log(url);
     // Exit with the same code as gh CLI
     process.exit(error.status ?? 1);
 }
@@ -184,7 +197,7 @@ function createIssue(title, body, labels) {
 /**
  * Submit feedback via gh CLI
  */
-function submitViaGhCli(title, body) {
+function submitViaGhCli(title, body, url) {
     let issueUrl;
     let labelApplied = true;
     try {
@@ -192,7 +205,7 @@ function submitViaGhCli(title, body) {
     }
     catch (error) {
         if (!isMissingLabelError(error)) {
-            reportGhFailure(error, title, body);
+            reportGhFailure(error, title, body, url);
             return;
         }
         // The repository does not define the 'feedback' label. Nothing was
@@ -202,7 +215,7 @@ function submitViaGhCli(title, body) {
             labelApplied = false;
         }
         catch (retryError) {
-            reportGhFailure(retryError, title, body);
+            reportGhFailure(retryError, title, body, url);
             return;
         }
     }
@@ -215,7 +228,7 @@ function submitViaGhCli(title, body) {
 /**
  * Handle fallback when gh CLI is not available or not authenticated
  */
-function handleFallback(title, body, reason) {
+function handleFallback(title, body, url, reason) {
     if (reason === 'missing') {
         console.log('⚠️  GitHub CLI not found. Manual submission required.');
     }
@@ -223,9 +236,8 @@ function handleFallback(title, body, reason) {
         console.log('⚠️  GitHub authentication required. Manual submission required.');
     }
     displayFormattedFeedback(title, body);
-    const manualUrl = generateManualSubmissionUrl(title, body);
     console.log('Please submit your feedback manually:');
-    console.log(manualUrl);
+    console.log(url);
     if (reason === 'unauthenticated') {
         console.log('\nTo auto-submit in the future: gh auth login');
     }
@@ -240,18 +252,19 @@ export class FeedbackCommand {
         // Format title and body once for all code paths
         const title = formatTitle(message);
         const body = formatBody(message, options?.body);
+        const url = generateManualSubmissionUrl(title, message, options?.body);
         // Check if gh CLI is installed
         if (!isGhInstalled()) {
-            handleFallback(title, body, 'missing');
+            handleFallback(title, body, url, 'missing');
             return;
         }
         // Check if gh CLI is authenticated
         if (!isGhAuthenticated()) {
-            handleFallback(title, body, 'unauthenticated');
+            handleFallback(title, body, url, 'unauthenticated');
             return;
         }
         // Submit via gh CLI
-        submitViaGhCli(title, body);
+        submitViaGhCli(title, body, url);
     }
 }
 //# sourceMappingURL=feedback.js.map

package/dist/commands/install-standalone.d.ts

@@ -0,0 +1,27 @@
+import { type CliInstallInfo } from '../core/version-check.js';
+export interface InstallTarget {
+    dir: string;
+    name: string;
+}
+/**
+ * Where the installer will put the binary. Mirrors install.sh and install.ps1,
+ * and is passed to them explicitly so both sides agree. The standalone binary
+ * reinstalls itself where it is, under its own name.
+ */
+export declare function resolveInstallTarget(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, standalonePath?: string | null): InstallTarget;
+/** The command that removes a package-manager install, or null when there is nothing to remove. */
+export declare function removeCommandFor(install: CliInstallInfo): string | null;
+/**
+ * Checks a download source given through the environment. Release files and
+ * SHA256SUMS come from the same place, so a remote plain-HTTP source could
+ * swap both: only https, or http to this machine. The host is parsed, not
+ * prefix-matched, and a user part (http://localhost:80@evil.example/) is
+ * refused.
+ */
+export declare function checkSource(label: string, value: string): string;
+/** Where the installer script comes from: OPENSPEC_DOWNLOAD_URL when set (mirrors, tests), else main. */
+export declare function installerBase(env?: NodeJS.ProcessEnv): string;
+export declare function installStandalone(options?: {
+    version?: string;
+}): Promise<void>;
+//# sourceMappingURL=install-standalone.d.ts.map

package/dist/commands/install-standalone.js

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import chalk from 'chalk';
+import { findCopiesOnPath, samePath } from '../utils/executable-path.js';
+import { getCliInstallInfo, getStandaloneBinaryPath, } from '../core/version-check.js';
+/**
+ * `openspec install`: installs the standalone binary (no Node.js needed) by
+ * running the same release installer the docs give users, then says how to
+ * retire the package-manager copy. It never removes that copy itself: switching
+ * is the user's choice, and so is when.
+ */
+// The installers come from main, which always has them; they then pick the
+// newest release whose files are all attached (see install.sh).
+const INSTALLER_BASE = 'https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary';
+const RELEASE_VERSION = /^v?\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?$/;
+/**
+ * Where the installer will put the binary. Mirrors install.sh and install.ps1,
+ * and is passed to them explicitly so both sides agree. The standalone binary
+ * reinstalls itself where it is, under its own name.
+ */
+export function resolveInstallTarget(env = process.env, platform = process.platform, standalonePath = getStandaloneBinaryPath()) {
+    const defaultName = platform === 'win32' ? 'openspec.exe' : 'openspec';
+    if (env.OPENSPEC_INSTALL_DIR) {
+        return { dir: path.resolve(env.OPENSPEC_INSTALL_DIR), name: env.OPENSPEC_INSTALL_NAME || defaultName };
+    }
+    if (standalonePath) {
+        return { dir: path.dirname(standalonePath), name: path.basename(standalonePath) };
+    }
+    if (platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+        return { dir: path.join(localAppData, 'Programs', 'openspec'), name: defaultName };
+    }
+    return { dir: path.join(os.homedir(), '.local', 'bin'), name: defaultName };
+}
+/** The command that removes a package-manager install, or null when there is nothing to remove. */
+export function removeCommandFor(install) {
+    if (install.scope !== 'global')
+        return null;
+    // The Homebrew formula keeps its own npm tree under Cellar; brew owns it.
+    if (install.location && /[\\/]Cellar[\\/]openspec[\\/]/i.test(install.location)) {
+        return 'brew uninstall openspec';
+    }
+    switch (install.packageManager) {
+        case 'npm':
+            return 'npm uninstall -g @fission-ai/openspec';
+        case 'pnpm':
+            return 'pnpm remove -g @fission-ai/openspec';
+        case 'yarn':
+            return 'yarn global remove @fission-ai/openspec';
+        case 'bun':
+            return 'bun remove -g @fission-ai/openspec';
+        case 'volta':
+            return 'volta uninstall @fission-ai/openspec';
+        default:
+            return null;
+    }
+}
+/**
+ * Checks a download source given through the environment. Release files and
+ * SHA256SUMS come from the same place, so a remote plain-HTTP source could
+ * swap both: only https, or http to this machine. The host is parsed, not
+ * prefix-matched, and a user part (http://localhost:80@evil.example/) is
+ * refused.
+ */
+export function checkSource(label, value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} is not a URL: ${value}`);
+    }
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.username || url.password || (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))) {
+        throw new Error(`${label} must use https (or http to localhost): ${value}`);
+    }
+    return url.href.replace(/\/+$/, '');
+}
+/** Where the installer script comes from: OPENSPEC_DOWNLOAD_URL when set (mirrors, tests), else main. */
+export function installerBase(env = process.env) {
+    if (env.OPENSPEC_RELEASES_URL)
+        checkSource('OPENSPEC_RELEASES_URL', env.OPENSPEC_RELEASES_URL);
+    return env.OPENSPEC_DOWNLOAD_URL ? checkSource('OPENSPEC_DOWNLOAD_URL', env.OPENSPEC_DOWNLOAD_URL) : INSTALLER_BASE;
+}
+// Fixed scripts: the installer URL reaches them as data (an argument, or an
+// environment variable), never as part of the command text.
+const POSIX_RUNNER = 'f=$(mktemp) || exit 1; { curl -fsSL "$1" -o "$f" 2>/dev/null || wget -q -O "$f" "$1"; } && sh "$f"; s=$?; rm -f "$f"; exit $s';
+const WINDOWS_RUNNER = 'irm $env:OPENSPEC_INSTALLER_URL | iex';
+/**
+ * Downloads and runs the installer with the same tools as the documented
+ * one-liners (curl or wget; PowerShell's irm), so proxies and certificates
+ * behave as they do for those. Saved to a file first on macOS and Linux:
+ * piped straight into sh, a failed download would look like a successful run.
+ */
+function runInstaller(scriptUrl, env) {
+    const windows = process.platform === 'win32';
+    const command = windows ? 'powershell.exe' : 'sh';
+    const args = windows
+        ? ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', WINDOWS_RUNNER]
+        : ['-c', POSIX_RUNNER, 'openspec-install', scriptUrl];
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: 'inherit',
+            env: windows ? { ...env, OPENSPEC_INSTALLER_URL: scriptUrl } : env,
+        });
+        child.on('error', reject);
+        child.on('close', (code) => resolve(code ?? 1));
+    });
+}
+export async function installStandalone(options = {}) {
+    const { version } = options;
+    if (version && version !== 'latest' && !RELEASE_VERSION.test(version)) {
+        throw new Error(`Not a release version: ${version}. Use one like 1.15.0, or leave it out for the latest.`);
+    }
+    const scriptUrl = `${installerBase()}/${process.platform === 'win32' ? 'install.ps1' : 'install.sh'}`;
+    const target = resolveInstallTarget();
+    const exitCode = await runInstaller(scriptUrl, {
+        ...process.env,
+        OPENSPEC_INSTALL_DIR: target.dir,
+        OPENSPEC_INSTALL_NAME: target.name,
+        ...(version && version !== 'latest' ? { OPENSPEC_VERSION: version } : {}),
+    });
+    if (exitCode !== 0) {
+        throw new Error(`The standalone install did not finish (installer: ${scriptUrl}).`);
+    }
+    const installedPath = path.join(target.dir, target.name);
+    const defaultName = process.platform === 'win32' ? 'openspec.exe' : 'openspec';
+    // A custom file name is never what `openspec` on PATH finds, so skip that check.
+    const first = target.name === defaultName ? findCopiesOnPath()[0] : undefined;
+    const runsStandalone = first !== undefined && samePath(first, installedPath);
+    // Run from a package manager, the old copy stays until the user removes it.
+    const remove = getStandaloneBinaryPath() ? null : removeCommandFor(getCliInstallInfo());
+    console.log();
+    if (runsStandalone) {
+        console.log('openspec now runs the standalone copy.');
+    }
+    else if (first) {
+        console.log(`${first} comes first on your PATH, so it still runs.`);
+    }
+    else if (target.name === defaultName) {
+        console.log('Open a new terminal so it picks up the new PATH.');
+    }
+    if (remove) {
+        console.log(runsStandalone ? 'To remove your package-manager copy:' : 'To switch, remove your package-manager copy:');
+        console.log(chalk.cyan(`  ${remove}`));
+    }
+    console.log(chalk.dim("Check with 'openspec version'; it shows (standalone)."));
+}
+//# sourceMappingURL=install-standalone.js.map

package/dist/commands/schema.js

@@ -1,7 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 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 { findApplyTracksWarning, parseSchema, SchemaValidationError, } from '../core/artifact-graph/schema.js';
@@ -602,7 +601,11 @@ export async function schemaValidateCommand(name, options) {
     }
 }
 export async function schemaForkCommand(source, name, options) {
-    const spinner = options?.json ? null : ora();
+    let spinner = null;
+    if (!options?.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora();
+    }
     try {
         const projectRoot = process.cwd();
         const destinationName = name || `${source}-custom`;
@@ -829,7 +832,11 @@ export async function schemaForkCommand(source, name, options) {
     }
 }
 export async function schemaInitCommand(name, options) {
-    const spinner = options?.json ? null : ora();
+    let spinner = null;
+    if (!options?.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora();
+    }
     try {
         const projectRoot = process.cwd();
         // Validate name

package/dist/commands/validate.js

@@ -1,4 +1,3 @@
-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';
@@ -12,6 +11,7 @@ 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';
+import { readConfigParseError } from '../core/project-config.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);
@@ -67,6 +67,28 @@ export class ValidateCommand {
         if (!root) {
             return;
         }
+        // Every other command ignores an unreadable or unparseable config with a
+        // warning, so validate is where CI has to catch it (#1892).
+        const configError = readConfigParseError(root.path);
+        if (configError) {
+            const unreadable = configError.kind === 'read';
+            const message = unreadable
+                ? `Could not read ${configError.filePath} (${configError.message}).`
+                : `Could not parse ${configError.filePath} (${configError.message}).`;
+            const fix = unreadable
+                ? `Make ${configError.filePath} a readable file, or remove it.`
+                : `Fix the YAML syntax in ${configError.filePath}.`;
+            const code = unreadable ? 'unreadable_config' : 'unparseable_config';
+            if (options.json) {
+                console.log(JSON.stringify({ status: [{ severity: 'error', code, message, fix }] }, null, 2));
+            }
+            else {
+                console.error(`Error: ${message}`);
+                console.error(`Fix: ${fix}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
         const interactive = isInteractive(options);
         // Archived-task linting is its own scope: it checks task completion of
         // already-archived changes, not delta specs (whose operations are already
@@ -356,7 +378,11 @@ export class ValidateCommand {
         }
     }
     async runBulkValidation(root, scope, opts) {
-        const spinner = !opts.json && isInteractive(opts) && canRenderSpinner() ? ora('Validating...').start() : undefined;
+        let spinner;
+        if (!opts.json && isInteractive(opts) && canRenderSpinner()) {
+            const { default: ora } = await import('ora');
+            spinner = ora('Validating...').start();
+        }
         const [changeIds, specIds] = await Promise.all([
             scope.changes ? this.listChangeIds(root) : Promise.resolve([]),
             scope.specs ? getSpecIds(root.path) : Promise.resolve([]),
@@ -527,7 +553,11 @@ export class ValidateCommand {
         // List first (may throw on a real archive-read failure), then start the
         // spinner so a thrown error never leaves a spinner spinning.
         const ids = await this.listArchivedChangeIds(root);
-        const spinner = !opts.json && isInteractive(opts) && canRenderSpinner() ? ora('Validating archived changes...').start() : undefined;
+        let spinner;
+        if (!opts.json && isInteractive(opts) && canRenderSpinner()) {
+            const { default: ora } = await import('ora');
+            spinner = ora('Validating archived changes...').start();
+        }
         // The archive is append-only and can hold thousands of changes; a single
         // run resolves them all under one constant projectRoot (root.path), so
         // memoize the schema→glob lookup to avoid re-parsing the same schema.yaml

package/dist/commands/workflow/instructions.js

@@ -4,7 +4,6 @@
  * Generates enriched instructions for creating artifacts or applying tasks.
  * Includes both artifact instructions and apply instructions.
  */
-import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
 import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
@@ -50,7 +49,11 @@ export async function instructionsCommand(artifactId, options) {
     if (!root) {
         return;
     }
-    const spinner = options.json ? undefined : ora('Generating instructions...').start();
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora('Generating instructions...').start();
+    }
     try {
         const planningHome = toPlanningHome(root);
         const projectRoot = root.path;
@@ -534,7 +537,11 @@ export async function applyInstructionsCommand(options) {
     if (!root) {
         return;
     }
-    const spinner = options.json ? undefined : ora('Generating apply instructions...').start();
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora('Generating apply instructions...').start();
+    }
     try {
         const planningHome = toPlanningHome(root);
         const projectRoot = root.path;
@@ -639,7 +646,11 @@ export async function archiveInstructionsCommand(options) {
     if (!root) {
         return;
     }
-    const spinner = options.json ? undefined : ora('Loading archive inputs...').start();
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora('Loading archive inputs...').start();
+    }
     try {
         const changeName = await validateChangeExists(options.change, root.path, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
         const projectConfig = readProjectConfig(root.path);

package/dist/commands/workflow/new-change.js

@@ -7,11 +7,11 @@
  * this command.
  */
 import chalk from 'chalk';
-import ora from 'ora';
 import path from 'path';
 import { createChange, validateChangeName } from '../../utils/change-utils.js';
 import { formatChangeLocation } from '../../core/planning-home.js';
 import { resolveRootForCommand, RootSelectionError, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
+import { readProjectConfig } from '../../core/project-config.js';
 import { printJson, statusFromError, validateSchemaExists } from './shared.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
@@ -53,7 +53,11 @@ function printImplicitRootNotice(root) {
     console.log(chalk.dim('Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.'));
 }
 export async function newChangeCommand(name, options) {
-    const spinner = options.json ? undefined : ora();
+    let spinner;
+    if (!options.json) {
+        const { default: ora } = await import('ora');
+        spinner = ora();
+    }
     try {
         if (!name) {
             throw new Error('Missing required argument <name>');
@@ -75,12 +79,16 @@ export async function newChangeCommand(name, options) {
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
-        const resolvedSchema = options.schema ?? root.defaultSchema;
+        // Resolve the schema once (--schema, then config, then the root default)
+        // and hand it to createChange, so the progress line names the schema the
+        // change gets and config warnings print only once. An empty --schema is
+        // absent, matching createChange's `if (options.schema)`.
+        const resolvedSchema = options.schema || (readProjectConfig(projectRoot)?.schema ?? root.defaultSchema);
         if (spinner) {
             spinner.start(`Creating change '${name}' with schema '${resolvedSchema}'...`);
         }
         const result = await createChange(projectRoot, name, {
-            schema: options.schema,
+            schema: resolvedSchema,
             defaultSchema: root.defaultSchema,
             changesDir: root.changesDir,
             metadata: {