@fission-ai/openspec 1.10.0 → 1.12.0

package/README.md

@@ -172,6 +172,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
 → **[Customization](docs/customization.md)**: make it yours<br>
+→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec<br>
 → **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
 

package/dist/cli/index.js

@@ -24,7 +24,7 @@ import { registerStoreCommand } from '../commands/store.js';
 import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
-import { statusCommand, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
 import { maybeShowCompletionTip } from '../core/completion-tip.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
@@ -366,6 +366,7 @@ changeCmd
     .option('--json', 'Output as JSON')
     .option('--deltas-only', 'Show only deltas (JSON only)')
     .option('--requirements-only', 'Alias for --deltas-only (deprecated)')
+    .option('--diff', 'Show per-requirement diffs for delta specs')
     .option('--no-interactive', 'Disable interactive prompts')
     .action(async (changeName, options) => {
     try {
@@ -448,6 +449,7 @@ program
     .option('--changes', 'Validate all changes')
     .option('--specs', 'Validate all specs')
     .option('--archived', 'Validate that archived changes have all tasks completed (for pre-commit linting)')
+    .option('--report <full|findings>', 'Select bulk report content: full|findings; combine with --json for JSON')
     .option('--type <type>', 'Specify item type when ambiguous: change|spec')
     .option('--strict', 'Enable strict validation mode')
     .option('--json', 'Output validation results as JSON')
@@ -475,6 +477,7 @@ program
     // change-only flags
     .option('--deltas-only', 'Show only deltas (JSON only, change)')
     .option('--requirements-only', 'Alias for --deltas-only (deprecated, change)')
+    .option('--diff', 'Show per-requirement diffs for delta specs (change)')
     // spec-only flags
     .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
     .option('--no-scenarios', 'JSON only: Exclude scenario content')
@@ -577,6 +580,7 @@ program
     .command('status')
     .description('Display artifact completion status for a change')
     .option('--change <id>', 'Change name to show status for')
+    .option('--all', 'Show status for all active changes')
     .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
     .option('--json', 'Output as JSON')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
@@ -586,7 +590,13 @@ program
         await statusCommand(options);
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, fallbackCode: 'change_error' });
+        failWithError(error, {
+            enabled: options.json,
+            // The batch null-shape; the single-change failure shape is
+            // pre-existing contract and stays payload-free.
+            payload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : undefined,
+            fallbackCode: 'change_error',
+        });
         process.exit(1);
     }
 });

package/dist/commands/change.d.ts

@@ -4,19 +4,43 @@ export declare class ChangeCommand {
     private rootPath?;
     constructor(rootPath?: string);
     private getChangesPath;
+    private getSpecsPath;
     /**
      * Show a change proposal.
      * - Text mode: raw markdown passthrough (no filters)
      * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
      *   Note: --requirements-only is deprecated alias for --deltas-only
+     * - --diff: per-requirement diffs of the delta specs against the main specs,
+     *   appended in text mode and attached to MODIFIED deltas in JSON mode
      */
     show(changeName?: string, options?: {
         json?: boolean;
         requirementsOnly?: boolean;
         deltasOnly?: boolean;
+        diff?: boolean;
         noInteractive?: boolean;
         rootOutput?: RootOutput;
     }): Promise<void>;
+    /**
+     * Read every delta spec under the change and pair each requirement with its
+     * counterpart in the main spec. Text mode and JSON mode both render from this
+     * one pass, so the two surfaces cannot drift apart.
+     */
+    private collectSpecDiffs;
+    /**
+     * Attach `diff` (or `warning`) to every MODIFIED delta in the JSON payload.
+     * Mutates the deltas array in place.
+     *
+     * The parsed Delta objects carry the requirement body in `description`, not
+     * the header name, so they are matched to parsed blocks by capability and
+     * source order: ChangeParser emits one Delta per MODIFIED block in that order.
+     */
+    private enrichDeltasWithDiffs;
+    /**
+     * Text mode: per-requirement diffs of the delta specs against the main specs.
+     */
+    private showSpecDiffs;
+    private printDiffText;
     /**
      * List active changes.
      * - Text default: IDs only; --long prints minimal details (title, counts)

package/dist/commands/change.js

@@ -1,5 +1,6 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import chalk from 'chalk';
 import { JsonConverter } from '../core/converters/json-converter.js';
 import { Validator } from '../core/validation/validator.js';
 import { VALIDATION_MESSAGES } from '../core/validation/constants.js';
@@ -8,6 +9,9 @@ import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds } from '../utils/item-discovery.js';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { foldRequirementName, parseDeltaSpec, } from '../core/parsers/requirement-blocks.js';
+import { extractRequirementBlock, diffRequirementBlock, buildRenameMap, } from '../utils/requirement-diff.js';
 /**
  * True only when `target` is definitively absent. An EACCES or I/O failure
  * means existence cannot be determined, so callers fall through to their
@@ -39,11 +43,18 @@ export class ChangeCommand {
     getChangesPath() {
         return path.join(this.rootPath ?? process.cwd(), 'openspec', 'changes');
     }
+    // Main specs resolve against the same root as changes, so `--diff` reads the
+    // selected store's specs rather than whatever sits under the cwd.
+    getSpecsPath() {
+        return path.join(this.rootPath ?? process.cwd(), 'openspec', 'specs');
+    }
     /**
      * Show a change proposal.
      * - Text mode: raw markdown passthrough (no filters)
      * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
      *   Note: --requirements-only is deprecated alias for --deltas-only
+     * - --diff: per-requirement diffs of the delta specs against the main specs,
+     *   appended in text mode and attached to MODIFIED deltas in JSON mode
      */
     async show(changeName, options) {
         const changesPath = this.getChangesPath();
@@ -109,6 +120,9 @@ export class ChangeCommand {
             const title = this.extractTitle(contentForTitle, changeName);
             const id = parsed.name;
             const deltas = parsed.deltas || [];
+            if (options.diff) {
+                await this.enrichDeltasWithDiffs(deltas, changeName, changesPath);
+            }
             const output = {
                 id,
                 title,
@@ -122,6 +136,215 @@ export class ChangeCommand {
             FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const content = await fs.readFile(proposalPath, 'utf-8');
             console.log(content);
+            if (options?.diff) {
+                await this.showSpecDiffs(changeName, changesPath);
+            }
+        }
+    }
+    /**
+     * Read every delta spec under the change and pair each requirement with its
+     * counterpart in the main spec. Text mode and JSON mode both render from this
+     * one pass, so the two surfaces cannot drift apart.
+     */
+    async collectSpecDiffs(changeName, changesPath) {
+        const specsDir = path.join(changesPath, changeName, 'specs');
+        const mainSpecsDir = this.getSpecsPath();
+        // Same discovery ChangeParser uses, so a nested capability (specs/<area>/<id>)
+        // is diffed rather than silently skipped, and the ids here match the `spec`
+        // field of the JSON deltas.
+        const discovered = await discoverSpecFiles(specsDir);
+        const capabilities = discovered.map(spec => spec.id);
+        const results = [];
+        for (const { id: capability, specFile: deltaSpecPath } of discovered) {
+            const deltaContent = await fs.readFile(deltaSpecPath, 'utf-8');
+            const mainSpecPath = path.join(mainSpecsDir, ...capability.split('/'), 'spec.md');
+            let mainContent = null;
+            try {
+                FileSystemUtils.assertPathWithin(mainSpecsDir, mainSpecPath);
+                mainContent = await fs.readFile(mainSpecPath, 'utf-8');
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+                // No main spec on disk. For ADDED requirements that is the ordinary new
+                // capability case; MODIFIED requirements are handled as a mismatch below.
+            }
+            const plan = parseDeltaSpec(deltaContent);
+            const renameMap = buildRenameMap(plan.renamed);
+            for (const block of plan.added) {
+                results.push({ capability, operation: 'ADDED', requirementName: block.name, raw: block.raw });
+            }
+            // Prefer the authored REMOVED block so its Reason/Migration text reaches
+            // the reader; the bullet-list form carries a name and nothing else.
+            const removedBlocks = new Map(plan.removedBlocks.map(block => [foldRequirementName(block.name), block.raw]));
+            for (const name of plan.removed) {
+                const raw = removedBlocks.get(foldRequirementName(name));
+                results.push({
+                    capability,
+                    operation: 'REMOVED',
+                    requirementName: name,
+                    raw: raw ?? `### Requirement: ${name}`,
+                });
+            }
+            for (const rename of plan.renamed) {
+                results.push({ capability, operation: 'RENAMED', requirementName: rename.to, raw: '', rename });
+            }
+            for (const block of plan.modified) {
+                const entry = {
+                    capability,
+                    operation: 'MODIFIED',
+                    requirementName: block.name,
+                    raw: block.raw,
+                };
+                // A requirement renamed and modified in the same delta still lives in
+                // the main spec under its old name, so look it up there.
+                const oldName = renameMap.get(foldRequirementName(block.name));
+                const lookupName = oldName ?? block.name;
+                const match = mainContent ? extractRequirementBlock(mainContent, lookupName) : null;
+                if (match) {
+                    entry.diff = diffRequirementBlock(match.raw, block.raw, `${capability}/${block.name}`);
+                    if (!match.exact) {
+                        // Archive matches requirement names exactly, so a header that
+                        // differs only in case or spacing will not merge. Show the diff the
+                        // author meant, and name the mismatch while it is still cheap to fix.
+                        entry.warning =
+                            `Header differs from the main spec's "${match.name}" only in case or spacing; ` +
+                                `archive matches names exactly, so reconcile them before archiving`;
+                    }
+                }
+                else if (mainContent) {
+                    entry.warning = `No matching main requirement found for "${lookupName}" in ${capability}`;
+                }
+                else {
+                    // A MODIFIED requirement names a block that should already exist, so a
+                    // missing main spec is an authoring error, not a new capability.
+                    // Rendering it as all-additions would hide what archive will reject.
+                    entry.warning =
+                        `No main spec at openspec/specs/${capability}/spec.md, ` +
+                            `so MODIFIED requirement "${block.name}" has nothing to diff against`;
+                }
+                results.push(entry);
+            }
+        }
+        return { capabilities, results };
+    }
+    /**
+     * Attach `diff` (or `warning`) to every MODIFIED delta in the JSON payload.
+     * Mutates the deltas array in place.
+     *
+     * The parsed Delta objects carry the requirement body in `description`, not
+     * the header name, so they are matched to parsed blocks by capability and
+     * source order: ChangeParser emits one Delta per MODIFIED block in that order.
+     */
+    async enrichDeltasWithDiffs(deltas, changeName, changesPath) {
+        const modifiedDeltasBySpec = new Map();
+        for (const delta of deltas) {
+            if (!delta.spec || delta.operation !== 'MODIFIED')
+                continue;
+            const list = modifiedDeltasBySpec.get(delta.spec) ?? [];
+            list.push(delta);
+            modifiedDeltasBySpec.set(delta.spec, list);
+        }
+        if (modifiedDeltasBySpec.size === 0)
+            return;
+        const { results } = await this.collectSpecDiffs(changeName, changesPath);
+        const modifiedEntriesBySpec = new Map();
+        for (const entry of results) {
+            if (entry.operation !== 'MODIFIED')
+                continue;
+            const list = modifiedEntriesBySpec.get(entry.capability) ?? [];
+            list.push(entry);
+            modifiedEntriesBySpec.set(entry.capability, list);
+        }
+        for (const [capability, modifiedDeltas] of modifiedDeltasBySpec) {
+            const entries = modifiedEntriesBySpec.get(capability) ?? [];
+            for (let i = 0; i < modifiedDeltas.length && i < entries.length; i++) {
+                const entry = entries[i];
+                if (entry.diff !== undefined) {
+                    modifiedDeltas[i].diff = entry.diff;
+                }
+                if (entry.warning !== undefined) {
+                    modifiedDeltas[i].warning = entry.warning;
+                }
+            }
+        }
+    }
+    /**
+     * Text mode: per-requirement diffs of the delta specs against the main specs.
+     */
+    async showSpecDiffs(changeName, changesPath) {
+        const { capabilities, results } = await this.collectSpecDiffs(changeName, changesPath);
+        console.log();
+        if (capabilities.length === 0 || results.length === 0) {
+            // Not an error: a change can be proposal-only. Saying so beats printing a
+            // heading with nothing under it.
+            console.log(`No delta specs to diff for change "${changeName}".`);
+            return;
+        }
+        console.log(chalk.bold('Specifications Changed (diffs)'));
+        console.log();
+        this.printDiffText(results);
+    }
+    printDiffText(results) {
+        let currentCap = '';
+        for (const r of results) {
+            if (r.capability !== currentCap) {
+                if (currentCap)
+                    console.log();
+                currentCap = r.capability;
+                console.log(chalk.bold.underline(currentCap));
+                console.log();
+            }
+            switch (r.operation) {
+                case 'ADDED':
+                    console.log(chalk.green.bold(`  ADDED: ${r.requirementName}`));
+                    for (const line of r.raw.split('\n')) {
+                        console.log(chalk.green(`    ${line}`));
+                    }
+                    console.log();
+                    break;
+                case 'REMOVED':
+                    console.log(chalk.red.bold(`  REMOVED: ${r.requirementName}`));
+                    for (const line of r.raw.split('\n')) {
+                        console.log(chalk.red(`    ${line}`));
+                    }
+                    console.log();
+                    break;
+                case 'RENAMED':
+                    console.log(chalk.cyan.bold(`  RENAMED: ${r.rename?.from} → ${r.rename?.to}`));
+                    console.log();
+                    break;
+                case 'MODIFIED':
+                    console.log(chalk.yellow.bold(`  MODIFIED: ${r.requirementName}`));
+                    if (r.warning) {
+                        console.log(chalk.yellow(`    ⚠ ${r.warning}`));
+                    }
+                    // A near-miss header carries both: the warning about the mismatch and
+                    // the diff against the block it almost matched.
+                    if (r.diff === undefined) {
+                        for (const line of r.raw.split('\n')) {
+                            console.log(`    ${line}`);
+                        }
+                    }
+                    else if (r.diff === '') {
+                        console.log(chalk.dim('    (no textual changes)'));
+                    }
+                    else {
+                        for (const line of r.diff.split('\n')) {
+                            if (line.startsWith('+')) {
+                                console.log(chalk.green(`    ${line}`));
+                            }
+                            else if (line.startsWith('-')) {
+                                console.log(chalk.red(`    ${line}`));
+                            }
+                            else {
+                                console.log(`    ${line}`);
+                            }
+                        }
+                    }
+                    console.log();
+                    break;
+            }
         }
     }
     /**
@@ -257,11 +480,12 @@ export class ChangeCommand {
             }
             else {
                 console.error(`Change "${changeName}" has issues`);
-                report.issues.forEach(issue => {
-                    const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
-                    const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
-                    console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
-                });
+            }
+            report.issues.forEach(issue => {
+                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                console.error(`${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+            });
+            if (!report.valid) {
                 // Next steps footer to guide fixing issues
                 this.printNextSteps(report.issues);
                 if (!options?.json) {

package/dist/commands/schema.d.ts

@@ -1,4 +1,9 @@
 import { Command } from 'commander';
+import * as fs from 'node:fs';
+/** @internal File-operation seam for transactional failure tests. */
+export declare const schemaInitFileOperations: {
+    renameSync: typeof fs.renameSync;
+};
 /**
  * Register the schema command and all its subcommands.
  */

package/dist/commands/schema.js

@@ -2,9 +2,10 @@ 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 } from 'yaml';
+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 { resolveConfigFilePath } from '../core/project-config.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 /**
  * Check all three locations for a schema and return which ones exist.
@@ -289,6 +290,65 @@ function fingerprintDir(dir) {
     walk(dir, '');
     return hash.digest('hex');
 }
+/** @internal File-operation seam for transactional failure tests. */
+export const schemaInitFileOperations = {
+    renameSync: fs.renameSync,
+};
+async function prepareDefaultConfigUpdate(projectRoot, schemaName) {
+    const configPath = resolveConfigFilePath(projectRoot) ??
+        path.join(projectRoot, 'openspec', 'config.yaml');
+    FileSystemUtils.assertProjectArtifactPath(projectRoot, configPath);
+    if (fs.existsSync(configPath)) {
+        const stats = fs.lstatSync(configPath);
+        if (stats.isSymbolicLink()) {
+            throw new Error(`Cannot set the default schema: ${path.basename(configPath)} must be a regular file, not a symbolic link`);
+        }
+        if (!stats.isFile()) {
+            throw new Error(`Cannot set the default schema: ${path.basename(configPath)} must be a regular file`);
+        }
+        if (!(await FileSystemUtils.canWriteFile(configPath)) ||
+            !(await FileSystemUtils.canWriteFile(path.dirname(configPath)))) {
+            throw new Error(`Cannot set the default schema: ${path.basename(configPath)} is not writable`);
+        }
+        const originalContent = fs.readFileSync(configPath);
+        const config = parseDocument(originalContent.toString('utf-8'));
+        if (config.errors.length > 0) {
+            throw new Error(`Cannot set the default schema: ${path.basename(configPath)} is invalid YAML`);
+        }
+        if (config.contents !== null && !isMap(config.contents)) {
+            throw new Error(`Cannot set the default schema: ${path.basename(configPath)} must contain a YAML object`);
+        }
+        config.set('schema', schemaName);
+        config.delete('defaultSchema');
+        return {
+            path: configPath,
+            content: Buffer.from(config.toString()),
+            originalContent,
+            originalMode: stats.mode,
+        };
+    }
+    if (!(await FileSystemUtils.canWriteFile(configPath))) {
+        throw new Error(`Cannot set the default schema: ${path.dirname(configPath)} is not writable`);
+    }
+    return {
+        path: configPath,
+        content: Buffer.from(stringifyYaml({ schema: schemaName })),
+        originalContent: null,
+        originalMode: null,
+    };
+}
+function configMatchesPreparedState(prepared) {
+    if (prepared.originalContent === null) {
+        return !fs.existsSync(prepared.path);
+    }
+    if (!fs.existsSync(prepared.path))
+        return false;
+    const stats = fs.lstatSync(prepared.path);
+    return (stats.isFile() &&
+        !stats.isSymbolicLink() &&
+        stats.mode === prepared.originalMode &&
+        fs.readFileSync(prepared.path).equals(prepared.originalContent));
+}
 /**
  * Default artifacts with descriptions for schema init.
  */
@@ -952,46 +1012,152 @@ export function registerSchemaCommand(program) {
                     tracks: 'tasks.md',
                 };
             }
-            // Replace only after all inputs have been collected and validated
-            if (schemaExists) {
-                if (spinner)
-                    spinner.start(`Removing existing schema '${name}'...`);
-                fs.rmSync(schemaDir, { recursive: true });
-            }
-            // Create schema directory
+            // Parse and serialize the config before staging any schema files. This
+            // makes malformed, non-object, linked, and read-only configs fail before
+            // an existing schema can be moved or a new one can appear.
+            const preparedConfig = options?.default
+                ? await prepareDefaultConfigUpdate(projectRoot, name)
+                : null;
+            const schemasDir = getProjectSchemasDir(projectRoot);
+            FileSystemUtils.assertProjectArtifactPath(projectRoot, schemaDir);
+            const authorizedSchemaFingerprint = schemaExists
+                ? fingerprintDir(schemaDir)
+                : null;
             if (spinner)
                 spinner.start(`Creating schema '${name}'...`);
-            fs.mkdirSync(schemaDir, { recursive: true });
-            fs.writeFileSync(path.join(schemaDir, 'schema.yaml'), stringifyYaml(schema));
-            // Create template files in templates/ subdirectory (standard location)
-            const templatesDir = path.join(schemaDir, 'templates');
-            for (const artifact of selectedArtifacts) {
-                const templatePath = path.join(templatesDir, artifact.template);
-                const templateDir = path.dirname(templatePath);
-                if (!fs.existsSync(templateDir)) {
-                    fs.mkdirSync(templateDir, { recursive: true });
+            fs.mkdirSync(schemasDir, { recursive: true });
+            const schemaStagingDir = fs.mkdtempSync(path.join(schemasDir, '.init-staging-'));
+            let configStagingDir = null;
+            let stagedConfigPath = null;
+            try {
+                fs.writeFileSync(path.join(schemaStagingDir, 'schema.yaml'), stringifyYaml(schema));
+                const templatesDir = path.join(schemaStagingDir, 'templates');
+                for (const artifact of selectedArtifacts) {
+                    const templatePath = path.join(templatesDir, artifact.template);
+                    fs.mkdirSync(path.dirname(templatePath), { recursive: true });
+                    fs.writeFileSync(templatePath, createDefaultTemplate(artifact.id));
+                }
+                const validation = validateSchema(schemaStagingDir);
+                if (!validation.valid) {
+                    throw new Error(`Generated schema failed validation: ${validation.issues
+                        .map((issue) => issue.message)
+                        .join('; ')}`);
+                }
+                if (preparedConfig) {
+                    const configDir = path.dirname(preparedConfig.path);
+                    configStagingDir = fs.mkdtempSync(path.join(configDir, '.schema-init-config-'));
+                    stagedConfigPath = path.join(configStagingDir, path.basename(preparedConfig.path));
+                    fs.writeFileSync(stagedConfigPath, preparedConfig.content);
+                    if (preparedConfig.originalMode !== null) {
+                        fs.chmodSync(stagedConfigPath, preparedConfig.originalMode);
+                    }
+                }
+                // Re-resolve both destinations immediately before the first move so
+                // a parent symlink swap during staging cannot redirect the commit.
+                FileSystemUtils.assertProjectArtifactPath(projectRoot, schemaDir);
+                if (preparedConfig) {
+                    FileSystemUtils.assertProjectArtifactPath(projectRoot, preparedConfig.path);
+                }
+                const currentSchemaFingerprint = fs.existsSync(schemaDir)
+                    ? fingerprintDir(schemaDir)
+                    : null;
+                if (currentSchemaFingerprint !== authorizedSchemaFingerprint) {
+                    throw new Error(`Schema '${name}' changed on disk while initialization was being prepared. ` +
+                        'Aborted to preserve those concurrent changes.');
+                }
+                if (preparedConfig && !configMatchesPreparedState(preparedConfig)) {
+                    throw new Error(`${path.basename(preparedConfig.path)} changed on disk while initialization was being prepared. ` +
+                        'Aborted to preserve those concurrent changes.');
+                }
+                const token = `${process.pid}-${Date.now()}`;
+                const schemaBackup = `${schemaDir}.init-backup-${token}`;
+                const configBackup = preparedConfig
+                    ? `${preparedConfig.path}.init-backup-${token}`
+                    : null;
+                let schemaBackedUp = false;
+                let configBackedUp = false;
+                let schemaInstalled = false;
+                let configInstalled = false;
+                try {
+                    if (schemaExists) {
+                        schemaInitFileOperations.renameSync(schemaDir, schemaBackup);
+                        schemaBackedUp = true;
+                    }
+                    if (preparedConfig && preparedConfig.originalContent !== null) {
+                        schemaInitFileOperations.renameSync(preparedConfig.path, configBackup);
+                        configBackedUp = true;
+                    }
+                    schemaInitFileOperations.renameSync(schemaStagingDir, schemaDir);
+                    schemaInstalled = true;
+                    if (preparedConfig && stagedConfigPath) {
+                        schemaInitFileOperations.renameSync(stagedConfigPath, preparedConfig.path);
+                        configInstalled = true;
+                    }
+                }
+                catch (installError) {
+                    const rollbackErrors = [];
+                    try {
+                        if (configInstalled && preparedConfig) {
+                            fs.rmSync(preparedConfig.path, { force: true });
+                        }
+                        if (configBackedUp && preparedConfig && configBackup) {
+                            schemaInitFileOperations.renameSync(configBackup, preparedConfig.path);
+                        }
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(`config: ${rollbackError.message}`);
+                    }
+                    try {
+                        if (schemaInstalled) {
+                            fs.rmSync(schemaDir, { recursive: true, force: true });
+                        }
+                        if (schemaBackedUp) {
+                            schemaInitFileOperations.renameSync(schemaBackup, schemaDir);
+                        }
+                    }
+                    catch (rollbackError) {
+                        rollbackErrors.push(`schema: ${rollbackError.message}`);
+                    }
+                    if (rollbackErrors.length > 0) {
+                        throw new Error(`Schema initialization failed and rollback was incomplete (${rollbackErrors.join(', ')}). ` +
+                            `Recovery backups may remain beside ${schemaDir} and ${preparedConfig?.path ?? 'the config file'}.`, { cause: installError });
+                    }
+                    throw installError;
+                }
+                // The transaction is committed. Cleanup cannot turn success into a
+                // false failure, so leave a recoverable backup and warn if removal is
+                // blocked instead of reporting that initialization failed.
+                for (const backup of [
+                    schemaBackedUp ? schemaBackup : null,
+                    configBackedUp ? configBackup : null,
+                ]) {
+                    if (!backup)
+                        continue;
+                    try {
+                        fs.rmSync(backup, { recursive: true, force: true });
+                    }
+                    catch (cleanupError) {
+                        console.error(`Warning: initialization succeeded, but the backup at ${backup} could not be removed: ${cleanupError.message}`);
+                    }
                 }
-                // Create default template content
-                const templateContent = createDefaultTemplate(artifact.id);
-                fs.writeFileSync(templatePath, templateContent);
             }
-            // Update config if --default
-            if (options?.default) {
-                const configPath = path.join(projectRoot, 'openspec', 'config.yaml');
-                if (fs.existsSync(configPath)) {
-                    const { parse: parseYaml, stringify: stringifyYaml2 } = await import('yaml');
-                    const configContent = fs.readFileSync(configPath, 'utf-8');
-                    const config = parseYaml(configContent) || {};
-                    config.defaultSchema = name;
-                    fs.writeFileSync(configPath, stringifyYaml2(config));
+            catch (error) {
+                try {
+                    fs.rmSync(schemaStagingDir, { recursive: true, force: true });
                 }
-                else {
-                    // Create config file
-                    const configDir = path.dirname(configPath);
-                    if (!fs.existsSync(configDir)) {
-                        fs.mkdirSync(configDir, { recursive: true });
+                catch {
+                    // Best-effort cleanup must not hide the operation's real error.
+                }
+                throw error;
+            }
+            finally {
+                if (configStagingDir) {
+                    try {
+                        fs.rmSync(configStagingDir, { recursive: true, force: true });
+                    }
+                    catch {
+                        // Best-effort cleanup. A committed config has already moved out.
                     }
-                    fs.writeFileSync(configPath, stringifyYaml({ defaultSchema: name }));
                 }
             }
             if (spinner)