@fission-ai/openspec 1.9.0 → 1.11.0

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)

package/dist/commands/show.js

@@ -4,7 +4,7 @@ import { resolveRootForCommand, toRootOutput, withStoreFlag, isStoreSelectedRoot
 import { ChangeCommand } from './change.js';
 import { SpecCommand } from './spec.js';
 import { nearestMatches } from '../utils/match.js';
-const CHANGE_FLAG_KEYS = new Set(['deltasOnly', 'requirementsOnly']);
+const CHANGE_FLAG_KEYS = new Set(['deltasOnly', 'requirementsOnly', 'diff']);
 const SPEC_FLAG_KEYS = new Set(['requirements', 'scenarios', 'requirement']);
 export class ShowCommand {
     async execute(itemName, options = {}) {

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

@@ -3,7 +3,7 @@
  *
  * Commands for the artifact-driven workflow: status, instructions, templates, schemas, new change.
  */
-export { statusCommand } from './status.js';
+export { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD } from './status.js';
 export type { StatusOptions } from './status.js';
 export { instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, } from './instructions.js';
 export type { InstructionsOptions } from './instructions.js';

package/dist/commands/workflow/index.js

@@ -3,7 +3,7 @@
  *
  * Commands for the artifact-driven workflow: status, instructions, templates, schemas, new change.
  */
-export { statusCommand } from './status.js';
+export { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD } from './status.js';
 export { instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, } from './instructions.js';
 export { templatesCommand } from './templates.js';
 export { schemasCommand } from './schemas.js';

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

@@ -6,11 +6,13 @@
 import { type ChangeStatus } from '../../core/artifact-graph/index.js';
 export interface StatusOptions {
     change?: string;
+    all?: boolean;
     schema?: string;
     store?: string;
     storePath?: string;
     json?: boolean;
 }
+export declare const BATCH_STATUS_FAILURE_PAYLOAD: Record<string, unknown>;
 export declare function statusCommand(options: StatusOptions): Promise<void>;
 export declare function printStatusText(status: ChangeStatus): void;
 //# sourceMappingURL=status.d.ts.map

package/dist/commands/workflow/status.js

@@ -8,14 +8,26 @@ import chalk from 'chalk';
 import { getChangeDir } from '../../core/planning-home.js';
 import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
 import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
+import { asStatus } from '../shared-output.js';
 import { validateChangeExists, validateSchemaExists, getAvailableChanges, getStatusIndicator, getStatusColor, } from './shared.js';
-// -----------------------------------------------------------------------------
-// Command Implementation
-// -----------------------------------------------------------------------------
+// The --all --json failure null-shape. Root-selection failures (handled in
+// resolveRootForCommand) and thrown errors (caught by the CLI wrapper) must
+// emit the same shape, so both call sites reference this one constant.
+export const BATCH_STATUS_FAILURE_PAYLOAD = {
+    changes: [],
+    root: null,
+};
 export async function statusCommand(options) {
+    if (options.all && options.change) {
+        throw new Error('The --all and --change options are mutually exclusive.');
+    }
     // The root resolves (and the store banner prints) before the spinner starts
-    // so the two do not fight over stderr.
-    const root = await resolveRootForCommand(options, { json: options.json });
+    // so the two do not fight over stderr. The batch null-shape rides along so
+    // a root-selection failure under --all --json still carries `changes: []`.
+    const root = await resolveRootForCommand(options, {
+        json: options.json,
+        failurePayload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : undefined,
+    });
     if (!root) {
         return;
     }
@@ -25,9 +37,20 @@ export async function statusCommand(options) {
         const projectRoot = root.path;
         const rootOutput = toRootOutput(root);
         const newChangeHint = withStoreFlag(root, 'openspec new change <name>');
+        // Single definition of "load one change's status" so the batch and
+        // single-change payloads can never drift apart.
+        const loadStatus = (changeName) => formatChangeStatus(loadChangeContext(projectRoot, changeName, options.schema, {
+            changeDir: getChangeDir(planningHome, changeName),
+            planningHome,
+        }), isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
         // Handle no-changes case gracefully — status is informational,
         // so "no changes" is a valid state, not an error.
         if (!options.change) {
+            // Validate before the no-changes early return so a bogus --schema
+            // fails the same way whether or not any change exists yet.
+            if (options.all && options.schema) {
+                validateSchemaExists(options.schema, projectRoot);
+            }
             const available = await getAvailableChanges(projectRoot, root.changesDir);
             if (available.length === 0) {
                 spinner?.stop();
@@ -38,9 +61,54 @@ export async function statusCommand(options) {
                 console.log(`No active changes. Create one with: ${newChangeHint}`);
                 return;
             }
-            // Changes exist but --change not provided
+            if (options.all) {
+                // readdir order is platform-dependent; sort for deterministic output,
+                // with the same comparator validate --all uses so the two batch
+                // commands order a given change set identically.
+                const entries = [];
+                for (const changeName of available.sort((a, b) => a.localeCompare(b))) {
+                    try {
+                        entries.push(loadStatus(changeName));
+                    }
+                    catch (error) {
+                        // One malformed change must not blank the sweep; carry its
+                        // diagnostic in place and keep going.
+                        entries.push({ changeName, status: [asStatus(error, 'change_error')] });
+                    }
+                }
+                spinner?.stop();
+                const failed = entries.some((entry) => !('artifacts' in entry));
+                if (options.json) {
+                    console.log(JSON.stringify({ changes: entries, root: rootOutput }, null, 2));
+                    if (failed) {
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+                entries.forEach((entry, index) => {
+                    if (index > 0) {
+                        console.log();
+                    }
+                    if ('artifacts' in entry) {
+                        printStatusText(entry);
+                    }
+                    else {
+                        console.log(chalk.red(`✗ ${entry.changeName}: ${entry.status[0]?.message}`));
+                    }
+                });
+                // A partial load is still a failed command in both output modes;
+                // JSON callers can parse the complete envelope independently of
+                // the process exit code.
+                if (failed) {
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            // Changes exist but neither --change nor --all provided. Name --all
+            // here too: it is the other way to answer this prompt, and a caller
+            // who wants every change should not have to find it in --help.
             spinner?.stop();
-            throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+            throw new Error(`Missing required option --change (or --all for every active change). Available changes:\n  ${available.join('\n  ')}`);
         }
         const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint });
         // Validate schema if explicitly provided
@@ -48,11 +116,7 @@ export async function statusCommand(options) {
             validateSchemaExists(options.schema, projectRoot);
         }
         // loadChangeContext will auto-detect schema from metadata if not provided
-        const context = loadChangeContext(projectRoot, changeName, options.schema, {
-            changeDir: getChangeDir(planningHome, changeName),
-            planningHome,
-        });
-        const status = formatChangeStatus(context, isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
+        const status = loadStatus(changeName);
         spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify({ ...status, root: rootOutput }, null, 2));

package/dist/core/archive.js

@@ -46,6 +46,33 @@ export async function isRetirableSpec(specName, rebuilt) {
     return (errors.length > 0 &&
         errors.every((issue) => issue.message === VALIDATION_MESSAGES.SPEC_NO_REQUIREMENTS));
 }
+/**
+ * How much of one blocking line the abort is willing to show. A line long
+ * enough to fill the screen would push the way out of the abort off it.
+ */
+const UNACCOUNTED_LINE_MAX = 200;
+/**
+ * The first few lines a retirement would delete without being able to name
+ * them, quoted, with a count for the rest. Capped so a long tail cannot bury
+ * the rest of the abort.
+ *
+ * The lines are authored spec content printed verbatim to a terminal, so they
+ * get the same treatment as a change directory name (`describeChangeName`): a
+ * raw CR could forge a line of its own, and an ESC could redraw the screen.
+ * Truncation counts code points so a cut never leaves half a surrogate pair.
+ */
+function describeUnaccountedContent(lines) {
+    const shown = lines
+        .slice(0, 3)
+        .map((line) => {
+        const safe = [...line.replace(/[\u0000-\u001f\u007f]/g, '?')];
+        const clipped = safe.slice(0, UNACCOUNTED_LINE_MAX).join('');
+        return `"${safe.length > UNACCOUNTED_LINE_MAX ? `${clipped}\u2026` : clipped}"`;
+    })
+        .join(', ');
+    const rest = lines.length > 3 ? `, and ${lines.length - 3} more line(s)` : '';
+    return `${shown}${rest}`;
+}
 async function isRetirementCandidate(update, built, skipValidation) {
     return (!skipValidation &&
         built.noRequirementBlocks &&
@@ -1252,17 +1279,24 @@ export class ArchiveCommand {
                                 const specName = p.update.id;
                                 const report = await new Validator().validateSpecContent(specName, p.rebuilt);
                                 if (!report.valid) {
+                                    // This run is what emptied the capability, and "no
+                                    // requirements" is the only thing wrong with the spec that
+                                    // would be written - so retiring it is what archive would do,
+                                    // and what stands in the way of that is worth saying. Not
+                                    // always the *only* fix: a live requirement can be hiding in a
+                                    // second `## Requirements` section the validator never reaches,
+                                    // and merging the sections fixes that spec without a deletion.
+                                    const emptiedByThisRun = p.update.exists &&
+                                        p.counts.removed > 0 &&
+                                        p.noRequirementBlocks &&
+                                        (await isRetirableSpec(specName, p.rebuilt));
                                     // The dead end #1302 describes: the rebuilt spec is unwritable
                                     // for exactly one reason, and retiring the capability is the
                                     // fix - but only the author can authorise deleting the spec, so
                                     // the abort names the marker instead of just rejecting. Says so
                                     // only when the marker is the ONLY thing missing, so it never
                                     // sends someone after a marker that would not have helped.
-                                    const retirementWouldFix = !retirementDeclared &&
-                                        p.update.exists &&
-                                        p.counts.removed > 0 &&
-                                        (await isRetirementCandidate(p.update, p, false));
-                                    const retirementHint = retirementWouldFix
+                                    const retirementHint = !retirementDeclared && emptiedByThisRun && p.unaccountedContent.length === 0
                                         ? `This change removes the last requirement '${specName}' has. To retire the` +
                                             ` capability and delete its spec, add \`retire_capabilities: true\` to the` +
                                             ` change's ${METADATA_FILENAME} (alongside its \`schema:\`, which that file` +
@@ -1271,6 +1305,27 @@ export class ArchiveCommand {
                                                 ? ` The marker present now cannot be honored (${retirementMarker.invalidReason}).`
                                                 : '')
                                         : undefined;
+                                    // #1696: the marker is missing AND the file holds content a
+                                    // retirement cannot account for, so this abort said nothing at
+                                    // all - just "must have at least one requirement", with no way
+                                    // forward. It names the content instead of the marker, on
+                                    // purpose: the marker is only ever named when adding it would
+                                    // really let the archive through, and here it would not. Once
+                                    // the content is resolved the rerun names the marker.
+                                    const blockedRetirementHint = !retirementDeclared && emptiedByThisRun && p.unaccountedContent.length > 0
+                                        ? `This change removes the last requirement '${specName}' has, so the rebuilt ` +
+                                            `spec has none left and cannot be written. Retiring the capability is what ` +
+                                            `archive does instead, and it is refused while the spec holds content the ` +
+                                            `merge cannot safely account for and deleting the file would take with it: ` +
+                                            `${describeUnaccountedContent(p.unaccountedContent)}. ` +
+                                            'Move it into `## Purpose` or a canonical requirement, or delete the spec by hand, then rerun.' +
+                                            // Said here too, because an author looking at a marker they
+                                            // believe authorises the deletion should not have to clear
+                                            // the content first to find out it was never read.
+                                            (retirementMarker.invalidReason
+                                                ? ` The marker present now cannot be honored (${retirementMarker.invalidReason}).`
+                                                : '')
+                                        : undefined;
                                     // The marker was set and retirement was still refused. Saying
                                     // nothing left the author who did exactly what the docs asked
                                     // back in the original dead end with no signal that their
@@ -1282,13 +1337,13 @@ export class ArchiveCommand {
                                         (await isRetirableSpec(specName, p.rebuilt))
                                         ? `'${specName}' declares retire_capabilities, but the spec holds content the merge ` +
                                             `cannot safely account for and deleting the file would take with it: ` +
-                                            `${p.unaccountedContent.slice(0, 3).map((line) => `"${line}"`).join(', ')}` +
-                                            `${p.unaccountedContent.length > 3 ? `, and ${p.unaccountedContent.length - 3} more line(s)` : ''}. ` +
+                                            `${describeUnaccountedContent(p.unaccountedContent)}. ` +
                                             'Move it into `## Purpose` or a canonical requirement, or delete the spec by hand.'
                                         : undefined;
                                     if (json) {
                                         throw new ArchiveBlockedError('archive_spec_validation_failed', `Rebuilt spec for '${specName}' failed validation. No files were changed.`, refusalReason ??
                                             retirementHint ??
+                                            blockedRetirementHint ??
                                             `Run ${withStoreFlag(root, `openspec validate ${specName}`)} after fixing the change deltas.`);
                                     }
                                     console.log(chalk.red(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`));
@@ -1300,6 +1355,8 @@ export class ArchiveCommand {
                                     }
                                     if (retirementHint)
                                         console.log(chalk.yellow(`  → ${retirementHint}`));
+                                    if (blockedRetirementHint)
+                                        console.log(chalk.yellow(`  → ${blockedRetirementHint}`));
                                     if (refusalReason)
                                         console.log(chalk.yellow(`  → ${refusalReason}`));
                                     console.log('Aborted. No files were changed.');

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

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { getSchemaDir, resolveSchema, listSchemasWithInfo } from './resolver.js';
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
-import { resolveArtifactOutputPath, resolveArtifactOutputs } from './outputs.js';
+import { isSpecsArtifactPath, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
 import { readChangeMetadata, resolveSchemaForChange } from '../../utils/change-metadata.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { buildActionContext, buildNextSteps, summarizePlanningHome, } from '../change-status-policy.js';
@@ -92,12 +92,7 @@ export function loadChangeContext(projectRoot, changeName, schemaName, options =
     const skippedArtifacts = new Set();
     if (metadata?.skip_specs) {
         for (const artifact of graph.getAllArtifacts()) {
-            // A schema may write generates as './specs/...' - the globs treat that
-            // identically to 'specs/...', so the skip set must too, or validate
-            // would honor the marker while instructions tell the agent to create
-            // the very files the conflict gate polices.
-            const generates = artifact.generates.replace(/^(?:\.\/)+/, '');
-            if (generates.startsWith('specs/') && !completed.has(artifact.id)) {
+            if (isSpecsArtifactPath(artifact.generates) && !completed.has(artifact.id)) {
                 completed.add(artifact.id);
                 skippedArtifacts.add(artifact.id);
             }

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

@@ -2,6 +2,10 @@
  * Checks if a path contains glob pattern characters.
  */
 export declare function isGlobPattern(pattern: string): boolean;
+/**
+ * Returns whether an artifact generates files under the change's specs/ tree.
+ */
+export declare function isSpecsArtifactPath(generates: string): boolean;
 export declare function resolveArtifactOutputPath(changeDir: string, generates: string): string;
 /**
  * Resolves an artifact's output path(s) to concrete files that currently exist.

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

@@ -8,6 +8,13 @@ import { FileSystemUtils } from '../../utils/file-system.js';
 export function isGlobPattern(pattern) {
     return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
 }
+/**
+ * Returns whether an artifact generates files under the change's specs/ tree.
+ */
+export function isSpecsArtifactPath(generates) {
+    const normalized = path.posix.normalize(FileSystemUtils.toPosixPath(generates));
+    return normalized.startsWith('specs/');
+}
 export function resolveArtifactOutputPath(changeDir, generates) {
     const outputPath = path.join(changeDir, generates);
     FileSystemUtils.assertPathWithin(changeDir, outputPath);

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

@@ -53,18 +53,24 @@ export function getProjectSchemasDir(projectRoot) {
  * @param entry - The directory entry from `fs.readdirSync(..., { withFileTypes: true })`
  */
 /**
- * Directories `schema fork` creates transiently while swapping a fork into
- * place: a staging copy (`.fork-staging-<rand>`, created via mkdtemp) and a
- * backup of the previous destination (`<name>.fork-backup-<pid>-<ts>`). Either
- * can briefly coexist with real schemas in the schemas dir, so discovery must
- * never surface them. Real schema names are kebab-case (no dots), so excluding
- * these dot-bearing temp names can never hide a legitimate schema.
+ * Directories `schema fork` and `schema init` create transiently while swapping
+ * a schema into place: a staging copy (`.fork-staging-<rand>` /
+ * `.init-staging-<rand>`, created via mkdtemp) and a backup of the previous
+ * destination (`<name>.fork-backup-<pid>-<ts>` /
+ * `<name>.init-backup-<pid>-<ts>`). Either can briefly coexist with real
+ * schemas in the schemas dir, and a backup outlives the run when its cleanup is
+ * blocked, so discovery must never surface them. Real schema names are
+ * kebab-case (no dots), so excluding these dot-bearing temp names can never
+ * hide a legitimate schema.
  */
-function isOwnedForkTempDir(name) {
-    return name.startsWith('.fork-staging-') || name.includes('.fork-backup-');
+function isOwnedTransientSchemaDir(name) {
+    return (name.startsWith('.fork-staging-') ||
+        name.includes('.fork-backup-') ||
+        name.startsWith('.init-staging-') ||
+        name.includes('.init-backup-'));
 }
 export function isSchemaDir(parentDir, entry) {
-    if (isOwnedForkTempDir(entry.name)) {
+    if (isOwnedTransientSchemaDir(entry.name)) {
         return false;
     }
     if (entry.isDirectory()) {