@fission-ai/openspec 1.8.0 → 1.10.0

package/dist/cli/index.d.ts

@@ -5,6 +5,38 @@ declare const program: Command;
  * For example: 'change show' -> 'change:show'
  */
 export declare function getCommandPath(command: Command): string;
+/**
+ * True when the executing command asked for JSON output — used to suppress the
+ * first-run telemetry notice so stdout stays a single valid JSON document.
+ *
+ * `--json` reaches commands three ways, so a single parsed option is not enough:
+ * - declared on the leaf (`openspec status --json`) → `opts().json`
+ * - declared on a parent group and read via globals (`openspec workset --json list`)
+ *   → `optsWithGlobals().json`
+ * - a residual arg on a permissive group that never declares the option
+ *   (`openspec store --json`, which detects it from `command.args`) → `args`
+ *
+ * Suppressing is always safe: the disclosure is only deferred to the next
+ * non-JSON run, never lost, whereas printing it on a JSON run corrupts stdout.
+ */
+export declare function isJsonRun(command: Command): boolean;
+/**
+ * True for the commands that exist to serve shell completions: the user-facing
+ * `openspec completion ...` group and the hidden `__complete` resolver that
+ * generated completion scripts call on every Tab press. Tipping either about
+ * completions is noise, and `__complete` would burn the one-shot tip invisibly.
+ */
+export declare function isCompletionRun(commandPath: string): boolean;
+/**
+ * True when the first-run completions tip must be deferred rather than shown.
+ *
+ * Deferring keeps the tip unconsumed, so it still reaches the user on a later
+ * run that can actually carry it. All three cases are runs nobody would read a
+ * hint from: JSON output, the completion machinery itself, and a stderr that is
+ * not a terminal — pipes and the agent-driven runs that dominate this CLI's
+ * usage would otherwise burn the user's one-shot tip into a log nobody opens.
+ */
+export declare function shouldDeferCompletionTip(command: Command, stderrIsTty: boolean): boolean;
 export { program };
 export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { createRequire } from 'module';
 import ora from 'ora';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { promises as fs } from 'fs';
+import { existsSync, promises as fs } from 'fs';
 import { AI_TOOLS, TOOL_ID_ALIASES } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
 import { getAvailableCliUpdate, displayCliUpdateNote, shouldOfferUpgrade, getInstallDir, offerCliUpgrade, rerunUpdateWithUpgradedCli, displayUpgradeCommand, isSourceCheckout, } from '../core/version-check.js';
@@ -26,6 +26,7 @@ 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 { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
+import { maybeShowCompletionTip } from '../core/completion-tip.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
 import { isInteractive } from '../utils/interactive.js';
 const STORE_OPTION_DESCRIPTION = COMMON_FLAGS.store.description;
@@ -72,6 +73,45 @@ export function getCommandPath(command) {
     }
     return names.join(':') || 'openspec';
 }
+/**
+ * True when the executing command asked for JSON output — used to suppress the
+ * first-run telemetry notice so stdout stays a single valid JSON document.
+ *
+ * `--json` reaches commands three ways, so a single parsed option is not enough:
+ * - declared on the leaf (`openspec status --json`) → `opts().json`
+ * - declared on a parent group and read via globals (`openspec workset --json list`)
+ *   → `optsWithGlobals().json`
+ * - a residual arg on a permissive group that never declares the option
+ *   (`openspec store --json`, which detects it from `command.args`) → `args`
+ *
+ * Suppressing is always safe: the disclosure is only deferred to the next
+ * non-JSON run, never lost, whereas printing it on a JSON run corrupts stdout.
+ */
+export function isJsonRun(command) {
+    return (command.optsWithGlobals().json === true ||
+        command.args.includes('--json'));
+}
+/**
+ * True for the commands that exist to serve shell completions: the user-facing
+ * `openspec completion ...` group and the hidden `__complete` resolver that
+ * generated completion scripts call on every Tab press. Tipping either about
+ * completions is noise, and `__complete` would burn the one-shot tip invisibly.
+ */
+export function isCompletionRun(commandPath) {
+    return commandPath.split(':')[0] === 'completion' || commandPath === '__complete';
+}
+/**
+ * True when the first-run completions tip must be deferred rather than shown.
+ *
+ * Deferring keeps the tip unconsumed, so it still reaches the user on a later
+ * run that can actually carry it. All three cases are runs nobody would read a
+ * hint from: JSON output, the completion machinery itself, and a stderr that is
+ * not a terminal — pipes and the agent-driven runs that dominate this CLI's
+ * usage would otherwise burn the user's one-shot tip into a log nobody opens.
+ */
+export function shouldDeferCompletionTip(command, stderrIsTty) {
+    return isJsonRun(command) || isCompletionRun(getCommandPath(command)) || !stderrIsTty;
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -87,15 +127,32 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    // Show first-run telemetry notice (if not seen)
-    await maybeShowTelemetryNotice();
+    // Show first-run telemetry notice (if not seen). It's written to stderr, so it
+    // never pollutes stdout — but --json runs still defer it (see isJsonRun) so the
+    // very first invocation stays free of any incidental output on either stream.
+    await maybeShowTelemetryNotice({ silent: isJsonRun(actionCommand) });
     // Track command execution (use actionCommand to get the actual subcommand)
     const commandPath = getCommandPath(actionCommand);
     await trackCommand(commandPath, version);
 });
 // Shutdown telemetry after command completes
-program.hook('postAction', async () => {
-    await shutdown();
+program.hook('postAction', async (_thisCommand, actionCommand) => {
+    // Show the first-run shell-completions tip (on stderr, so piped stdout stays
+    // clean). postAction, not preAction: the tip trails the command's own output
+    // instead of pushing an error message or `init`'s setup summary down the
+    // screen. Deferred — not consumed — whenever nobody would read it: JSON runs,
+    // `openspec completion ...`, and a stderr that is not a terminal (agents and
+    // pipes would otherwise silently burn the user's one-shot tip).
+    try {
+        await maybeShowCompletionTip({
+            silent: shouldDeferCompletionTip(actionCommand, Boolean(process.stderr.isTTY)),
+        });
+    }
+    finally {
+        // The flush runs even if the hint throws: parse() is synchronous, so a
+        // rejection here has no catch anywhere above it.
+        await shutdown();
+    }
 });
 const availableToolIds = AI_TOOLS
     .filter((tool) => tool.skillsDir || tool.globalSkillsDir)
@@ -108,6 +165,7 @@ program
     .command('init [path]')
     .description('Initialize OpenSpec in your project')
     .option('--tools <tools>', toolsOptionDescription)
+    .option('--language <language>', 'Write new OpenSpec artifacts in this language')
     .option('--force', 'Auto-cleanup legacy files without prompting')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
     .option('--no-animation', 'Show a static welcome screen instead of the animated one')
@@ -138,6 +196,7 @@ program
         const { InitCommand } = await import('../core/init.js');
         const initCommand = new InitCommand({
             tools: options?.tools,
+            language: options?.language,
             force: options?.force,
             profile: options?.profile,
             animation: options?.animation,
@@ -246,6 +305,9 @@ program
         const root = await resolveRootForCommand(options ?? {}, {
             json: options?.json,
             failurePayload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            // Preserve the cwd fallback for pre-config.yaml projects. The resolver
+            // still lets a registered/default store take precedence over it.
+            allowImplicitRoot: existsSync(path.join(process.cwd(), 'openspec', 'project.md')),
         });
         if (!root) {
             return;
@@ -340,10 +402,12 @@ changeCmd
     .action(async (changeName, options) => {
     try {
         const changeCommand = new ChangeCommand();
+        // validate() already sets process.exitCode, and Node honours it at
+        // natural exit. Calling process.exit() here would skip commander's
+        // postAction hook — the same trap called out for `update` below — which
+        // kills the telemetry flush and the first-run completions tip on what is
+        // a routine outcome, not an error: a change that fails validation.
         await changeCommand.validate(changeName, options);
-        if (typeof process.exitCode === 'number' && process.exitCode !== 0) {
-            process.exit(process.exitCode);
-        }
     }
     catch (error) {
         console.error(`Error: ${error.message}`);
@@ -383,6 +447,7 @@ program
     .option('--all', 'Validate all changes and specs')
     .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('--type <type>', 'Specify item type when ambiguous: change|spec')
     .option('--strict', 'Enable strict validation mode')
     .option('--json', 'Output validation results as JSON')
@@ -572,12 +637,18 @@ program
     .command('schemas')
     .description('List available workflow schemas with descriptions')
     .option('--json', 'Output as JSON (for agent use)')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
     .action(async (options) => {
     try {
         await schemasCommand(options);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options.json,
+            payload: { schemas: [], root: null },
+            fallbackCode: 'schemas_error',
+        });
         process.exit(1);
     }
 });

package/dist/commands/change.js

@@ -246,6 +246,7 @@ export class ChangeCommand {
             // Derived from changesPath so the main specs come from the same root the
             // change itself was resolved against.
             mainSpecsDir: path.join(path.dirname(changesPath), 'specs'),
+            projectRoot: path.dirname(path.dirname(changesPath)),
         });
         if (options?.json) {
             console.log(JSON.stringify(report, null, 2));

package/dist/commands/config.d.ts

@@ -10,6 +10,11 @@ interface ProfileStateDiff {
     hasChanges: boolean;
     lines: string[];
 }
+interface WorkflowPromptMeta {
+    name: string;
+    description: string;
+}
+export declare const WORKFLOW_PROMPT_META: Record<string, WorkflowPromptMeta>;
 /**
  * Resolve the effective current profile state from global config defaults.
  */

package/dist/commands/config.js

@@ -8,7 +8,7 @@ import { OPENSPEC_DIR_NAME } from '../core/config.js';
 import { hasProjectConfigDrift } from '../core/profile-sync-drift.js';
 import { UpdateCommand } from '../core/update.js';
 import { asErrorMessage, isPromptCancellationError } from './shared-output.js';
-const WORKFLOW_PROMPT_META = {
+export const WORKFLOW_PROMPT_META = {
     propose: {
         name: 'Propose change',
         description: 'Create proposal, design, and tasks from a request',
@@ -29,6 +29,10 @@ const WORKFLOW_PROMPT_META = {
         name: 'Apply tasks',
         description: 'Implement tasks from the current change',
     },
+    update: {
+        name: 'Update change',
+        description: 'Revise the planning artifacts of an existing change',
+    },
     ff: {
         name: 'Fast-forward',
         description: 'Run a faster implementation workflow',
@@ -449,6 +453,7 @@ export function registerConfigCommand(program) {
                 delivery: currentState.delivery,
                 workflows: [...currentState.workflows],
             };
+            let workflowSelectionChanged = false;
             if (action === 'both' || action === 'delivery') {
                 const deliveryChoices = [
                     {
@@ -493,8 +498,11 @@ export function registerConfigCommand(program) {
                     };
                 };
                 const selectedWorkflows = await checkbox({
+                    // The `instructions` option was removed in @inquirer/checkbox v5.
+                    // Its replacement, the built-in keys help tip, renders
+                    // "↑↓ navigate • space select • ⏎ submit" by default — a superset of
+                    // the hint this used to pass — so no theme override is needed here.
                     message: 'Select workflows to make available:',
-                    instructions: 'Space to toggle, Enter to confirm',
                     pageSize: ALL_WORKFLOWS.length,
                     theme: {
                         icon: {
@@ -505,7 +513,12 @@ export function registerConfigCommand(program) {
                     choices: ALL_WORKFLOWS.map(formatWorkflowChoice),
                 });
                 nextState.workflows = selectedWorkflows;
-                nextState.profile = deriveProfileFromWorkflowSelection(selectedWorkflows);
+                workflowSelectionChanged =
+                    selectedWorkflows.length !== currentState.workflows.length ||
+                        selectedWorkflows.some((workflow) => !currentState.workflows.includes(workflow));
+                nextState.profile = workflowSelectionChanged
+                    ? deriveProfileFromWorkflowSelection(selectedWorkflows)
+                    : currentState.profile;
             }
             const diff = diffProfileState(currentState, nextState);
             if (!diff.hasChanges) {
@@ -520,7 +533,9 @@ export function registerConfigCommand(program) {
             console.log();
             config.profile = nextState.profile;
             config.delivery = nextState.delivery;
-            config.workflows = nextState.workflows;
+            if (currentState.profile !== 'custom' || workflowSelectionChanged) {
+                config.workflows = nextState.workflows;
+            }
             saveGlobalConfig(config);
             // Check if inside an OpenSpec project
             const projectDir = process.cwd();

package/dist/commands/feedback.js

@@ -2,6 +2,8 @@ import { execSync, execFileSync } from 'child_process';
 import { createRequire } from 'module';
 import os from 'os';
 const require = createRequire(import.meta.url);
+const MAX_TITLE_LENGTH = 72;
+const TITLE_PREFIX = 'Feedback: ';
 /**
  * Check if gh CLI is installed and available in PATH
  * Uses platform-appropriate command: 'where' on Windows, 'which' on Unix/macOS
@@ -69,18 +71,37 @@ Submitted via OpenSpec CLI
  * Format the feedback title
  */
 function formatTitle(message) {
-    return `Feedback: ${message}`;
+    const normalizedMessage = message.replace(/\s+/g, ' ').trim();
+    const title = `${TITLE_PREFIX}${normalizedMessage}`;
+    if (Array.from(title).length <= MAX_TITLE_LENGTH) {
+        return title;
+    }
+    const availableLength = MAX_TITLE_LENGTH - TITLE_PREFIX.length - 1;
+    let candidate = '';
+    let candidateLength = 0;
+    const segments = new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(normalizedMessage);
+    for (const { segment } of segments) {
+        const segmentLength = Array.from(segment).length;
+        if (candidateLength + segmentLength > availableLength) {
+            break;
+        }
+        candidate += segment;
+        candidateLength += segmentLength;
+    }
+    candidate = candidate.trimEnd();
+    const lastSpace = candidate.lastIndexOf(' ');
+    const summary = lastSpace > 0 ? candidate.slice(0, lastSpace) : candidate;
+    return `${TITLE_PREFIX}${summary}…`;
 }
 /**
  * Format the full feedback body
  */
-function formatBody(bodyText) {
-    const parts = [];
+function formatBody(message, bodyText) {
+    const parts = ['## Summary', '', message];
     if (bodyText) {
-        parts.push(bodyText);
-        parts.push(''); // Empty line before metadata
+        parts.push('', '## Details', '', bodyText);
     }
-    parts.push(generateMetadata());
+    parts.push('', generateMetadata());
     return parts.join('\n');
 }
 /**
@@ -216,7 +237,7 @@ export class FeedbackCommand {
     async execute(message, options) {
         // Format title and body once for all code paths
         const title = formatTitle(message);
-        const body = formatBody(options?.body);
+        const body = formatBody(message, options?.body);
         // Check if gh CLI is installed
         if (!isGhInstalled()) {
             handleFallback(title, body, 'missing');

package/dist/commands/schema.js

@@ -1,7 +1,8 @@
 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 } from 'yaml';
+import { stringify as stringifyYaml, parseDocument } 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 { FileSystemUtils } from '../utils/file-system.js';
@@ -240,6 +241,54 @@ function assertSchemaTreeCanBeCopied(src, allowedRoot = src, ancestors = new Set
         ancestors.delete(canonicalSrc);
     }
 }
+/**
+ * Produces a stable content fingerprint of a directory: a SHA-256 over every
+ * file's relative path AND its bytes (plus directory paths), walked in sorted
+ * order. Two directories with byte-identical trees produce the same digest, and
+ * ANY change to a file's contents, size, or the set of paths changes it. Used to
+ * detect a concurrent modification of a fork destination between the moment the
+ * overwrite is authorized and the moment it is actually moved/deleted, so those
+ * changes are never silently destroyed.
+ */
+function fingerprintDir(dir) {
+    const hash = createHash('sha256');
+    const walk = (current, rel) => {
+        const entries = fs
+            .readdirSync(current, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const abs = path.join(current, entry.name);
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            // Use the entry type from readdir (no separate lstat), then read the file
+            // directly — avoiding a stat-then-read check/use gap. Size is derived from
+            // the bytes actually read, so the digest still covers content and length.
+            if (entry.isDirectory()) {
+                hash.update(`D:${relPath}\n`);
+                walk(abs, relPath);
+            }
+            else if (entry.isFile()) {
+                const contents = fs.readFileSync(abs);
+                hash.update(`F:${relPath}:${contents.length}:`);
+                hash.update(contents);
+                hash.update('\n');
+            }
+            else {
+                // Symlinks / other entry types: record the type + path (and the link
+                // target when readable) so a swap of one for another is still detected.
+                let target = '';
+                try {
+                    target = fs.readlinkSync(abs);
+                }
+                catch {
+                    // Non-symlink or unreadable target; the type marker below suffices.
+                }
+                hash.update(`O:${relPath}:${target}\n`);
+            }
+        }
+    };
+    walk(dir, '');
+    return hash.digest('hex');
+}
 /**
  * Default artifacts with descriptions for schema init.
  */
@@ -556,39 +605,155 @@ export function registerSchemaCommand(program) {
             // Validate the complete source before a forced fork removes anything.
             const trustedSourceDir = fs.realpathSync(sourceDir);
             assertSchemaTreeCanBeCopied(trustedSourceDir);
+            // Validate the source's schema content up front too, so a structurally
+            // invalid source is rejected before the --force path can remove an
+            // existing destination. This keeps `fork --force` atomic — an unusable
+            // source never destroys a valid destination — matching `schema init`,
+            // which likewise validates before it overwrites.
+            parseSchema(fs.readFileSync(path.join(trustedSourceDir, 'schema.yaml'), 'utf-8'));
             // Check destination
-            const destinationDir = path.join(getProjectSchemasDir(projectRoot), destinationName);
-            if (fs.existsSync(destinationDir)) {
-                if (!options?.force) {
-                    if (options?.json) {
-                        console.log(JSON.stringify({
-                            forked: false,
-                            error: `Schema '${destinationName}' already exists`,
-                            suggestion: 'Use --force to overwrite',
-                        }, null, 2));
+            const schemasDir = getProjectSchemasDir(projectRoot);
+            const destinationDir = path.join(schemasDir, destinationName);
+            // Reject a self-fork. Forking a schema onto itself with --force would
+            // otherwise remove the source at the replacement step below and then
+            // fail the copy, destroying the only copy of the schema. Resolve both
+            // sides to their real paths (realpathSync follows symlinks; path.resolve
+            // is a fallback only for a destination that does not exist yet) so a
+            // symlink or a `.`/`..` spelling of the same directory is still caught.
+            const resolvedDestination = fs.existsSync(destinationDir)
+                ? fs.realpathSync(destinationDir)
+                : path.resolve(destinationDir);
+            if (resolvedDestination === trustedSourceDir) {
+                throw new Error(`Cannot fork schema '${source}' onto itself; choose a different destination name`);
+            }
+            const destinationExists = fs.existsSync(destinationDir);
+            if (destinationExists && !options?.force) {
+                if (options?.json) {
+                    console.log(JSON.stringify({
+                        forked: false,
+                        error: `Schema '${destinationName}' already exists`,
+                        suggestion: 'Use --force to overwrite',
+                    }, null, 2));
+                }
+                else {
+                    console.error(`Error: Schema '${destinationName}' already exists at ${destinationDir}`);
+                    console.error('Use --force to overwrite');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // Fingerprint the destination the user authorized us to overwrite, BEFORE
+            // we spend time staging. Staging can take a while, and a concurrent
+            // process may edit the destination in that window; the fingerprint lets
+            // us detect such a change and abort rather than clobber it.
+            const authorizedDestinationFingerprint = destinationExists
+                ? fingerprintDir(destinationDir)
+                : null;
+            // Stage the complete fork in a temporary sibling directory first, then
+            // swap it into place. This keeps `fork --force` atomic: an existing
+            // destination is only removed once the new fork has been fully copied,
+            // name-updated, and (via the up-front parseSchema above) validated. Any
+            // failure while staging leaves both the source and the existing
+            // destination exactly as they were.
+            if (spinner)
+                spinner.start(`Forking '${source}' to '${destinationName}'...`);
+            fs.mkdirSync(schemasDir, { recursive: true });
+            const stagingDir = fs.mkdtempSync(path.join(schemasDir, '.fork-staging-'));
+            try {
+                copyDirRecursive(trustedSourceDir, stagingDir);
+                // Update name in the staged schema.yaml via yaml's Document API
+                // instead of re-serializing the parsed object, so block scalars,
+                // comments, and key order in the source schema.yaml survive the fork.
+                const stagedSchemaPath = path.join(stagingDir, 'schema.yaml');
+                const schemaContent = fs.readFileSync(stagedSchemaPath, 'utf-8');
+                const doc = parseDocument(schemaContent);
+                doc.set('name', destinationName);
+                fs.writeFileSync(stagedSchemaPath, doc.toString());
+                // Authoritative gate: validate the COMPLETED staged schema — the exact
+                // bytes we are about to install — not just the source at the pre-check.
+                // The source files copyDirRecursive reads can change mid-copy, so a
+                // source that was valid up front can still produce an invalid staged
+                // fork. Validating here, before ANY destructive step, guarantees we
+                // never install an invalid fork or delete a valid destination for one.
+                try {
+                    parseSchema(fs.readFileSync(stagedSchemaPath, 'utf-8'));
+                }
+                catch (validationError) {
+                    throw new Error(`The staged fork of '${source}' is not a valid schema (the source may have changed during copy); ` +
+                        `aborted, '${destinationName}' was not modified.`, { cause: validationError });
+                }
+                // Swap the staged fork into place. When a destination already exists,
+                // move it aside to a sibling backup FIRST, then install the staged
+                // fork; only once the install succeeds is the backup discarded. If the
+                // install rename itself fails (e.g. a Windows lock), the backup is
+                // moved back so the user's original destination is never lost.
+                if (destinationExists) {
+                    if (spinner)
+                        spinner.text = `Replacing existing schema '${destinationName}'...`;
+                    // Revalidate immediately before the destructive move: if the
+                    // destination changed on disk while we were staging (or was removed),
+                    // its fingerprint no longer matches what the user authorized. Abort
+                    // WITHOUT touching it, so the concurrent changes are preserved. The
+                    // outer catch cleans up staging.
+                    const currentFingerprint = fs.existsSync(destinationDir)
+                        ? fingerprintDir(destinationDir)
+                        : null;
+                    if (currentFingerprint !== authorizedDestinationFingerprint) {
+                        throw new Error(`Schema '${destinationName}' at ${destinationDir} changed on disk while the fork was being prepared. ` +
+                            `Aborted to preserve those concurrent changes; nothing was overwritten. Re-run the fork to overwrite the current contents.`);
+                    }
+                    const backupDir = `${destinationDir}.fork-backup-${process.pid}-${Date.now()}`;
+                    fs.renameSync(destinationDir, backupDir);
+                    try {
+                        fs.renameSync(stagingDir, destinationDir);
+                    }
+                    catch (installError) {
+                        // Install failed after the original was moved aside. Try to move
+                        // it back. If that restore ALSO fails, the original is stranded in
+                        // the backup dir — surface an error naming both the backup and the
+                        // destination so the user can recover manually, and attach the
+                        // original install error as the cause. Never swallow this.
+                        try {
+                            fs.renameSync(backupDir, destinationDir);
+                        }
+                        catch (restoreError) {
+                            throw new Error(`Failed to install the forked schema and could not restore the previous '${destinationName}'. ` +
+                                `Your previous schema is preserved at ${backupDir}; move it back to ${destinationDir} to restore. ` +
+                                `Restore error: ${restoreError.message}`, { cause: installError });
+                        }
+                        throw installError;
+                    }
+                    // Revalidate before discarding the backup: only delete it if it is
+                    // still byte-for-byte the original destination we moved aside. If it
+                    // changed during the install window (a concurrent write to the
+                    // moved-aside directory), do NOT delete it — leave it in place and
+                    // surface where it is so nothing is lost.
+                    if (fingerprintDir(backupDir) === authorizedDestinationFingerprint) {
+                        fs.rmSync(backupDir, { recursive: true, force: true });
                     }
                     else {
-                        console.error(`Error: Schema '${destinationName}' already exists at ${destinationDir}`);
-                        console.error('Use --force to overwrite');
+                        console.error(`Warning: the previous '${destinationName}' changed during the fork and was NOT deleted; ` +
+                            `its pre-fork copy is preserved at ${backupDir}.`);
                     }
-                    process.exitCode = 1;
-                    return;
                 }
-                // Remove existing
-                if (spinner)
-                    spinner.start(`Removing existing schema '${destinationName}'...`);
-                fs.rmSync(destinationDir, { recursive: true });
+                else {
+                    fs.renameSync(stagingDir, destinationDir);
+                }
+            }
+            catch (error) {
+                // Remove only the staging directory we created this run; the source
+                // and any existing destination are left exactly as we found them.
+                // Guard the cleanup in its own try/catch so a failed removal (e.g. a
+                // locked file on Windows) can never mask the original error, then
+                // rethrow so the real failure still drives the JSON/exit-code report.
+                try {
+                    fs.rmSync(stagingDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup; the original error below is what matters.
+                }
+                throw error;
             }
-            // Copy schema
-            if (spinner)
-                spinner.start(`Forking '${source}' to '${destinationName}'...`);
-            copyDirRecursive(trustedSourceDir, destinationDir);
-            // Update name in schema.yaml
-            const destSchemaPath = path.join(destinationDir, 'schema.yaml');
-            const schemaContent = fs.readFileSync(destSchemaPath, 'utf-8');
-            const schema = parseSchema(schemaContent);
-            schema.name = destinationName;
-            fs.writeFileSync(destSchemaPath, stringifyYaml(schema));
             if (spinner)
                 spinner.succeed(`Forked '${source}' to '${destinationName}'`);
             if (options?.json) {

package/dist/commands/validate.d.ts

@@ -2,6 +2,7 @@ interface ExecuteOptions {
     all?: boolean;
     changes?: boolean;
     specs?: boolean;
+    archived?: boolean;
     type?: string;
     strict?: boolean;
     json?: boolean;
@@ -29,6 +30,28 @@ export declare class ValidateCommand {
     private printReport;
     private printNextSteps;
     private runBulkValidation;
+    /**
+     * Lists archived change ids from the resolved root's archive directory,
+     * mirroring `getArchivedChangeIds` but store-aware (uses `root.archiveDir`
+     * rather than a cwd-relative path). Directories only, hidden entries skipped.
+     *
+     * Only a missing archive directory (ENOENT) is an empty list; a permission
+     * error, an I/O error, or an `archive` path that is a file (ENOTDIR) is a real
+     * failure and must not read as "no archived changes" — that would let a
+     * pre-commit lint pass without inspecting anything (#205).
+     */
+    private listArchivedChangeIds;
+    /**
+     * Validates that every archived change has all of its tasks completed.
+     *
+     * An archived change is expected to be finished; an archived change with
+     * unchecked tasks is a real integrity problem the normal validate flow never
+     * surfaces, because active-change discovery excludes the archive directory
+     * (#205). Reuses the same task-progress counting `status`, `list`, and
+     * `archive` rely on, so what counts as a task never forks. Changes with no
+     * tasks pass (nothing to complete).
+     */
+    private runArchivedTaskValidation;
 }
 export {};
 //# sourceMappingURL=validate.d.ts.map