@fission-ai/openspec 1.8.0 → 1.9.0

package/dist/cli/index.d.ts

@@ -5,6 +5,21 @@ 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;
 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';
@@ -72,6 +72,24 @@ 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'));
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -87,8 +105,9 @@ 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). Suppress it whenever the run
+    // asked for JSON so stdout stays a single valid JSON document (see isJsonRun).
+    await maybeShowTelemetryNotice({ silent: isJsonRun(actionCommand) });
     // Track command execution (use actionCommand to get the actual subcommand)
     const commandPath = getCommandPath(actionCommand);
     await trackCommand(commandPath, version);
@@ -246,6 +265,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;
@@ -383,6 +405,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 +595,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',

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

package/dist/commands/validate.js

@@ -7,15 +7,33 @@ import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';
 import { getAvailableChanges } from './workflow/shared.js';
 import { nearestMatches } from '../utils/match.js';
+import { promises as fs } from 'fs';
+import { getTaskProgressDetailForChange } from '../utils/task-progress.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 export class ValidateCommand {
     async execute(itemName, options = {}) {
-        const root = await resolveRootForCommand(options, { json: options.json });
+        const bulk = options.all || options.changes || options.specs;
+        const root = await resolveRootForCommand(options, {
+            json: options.json,
+            ...(bulk ? { allowImplicitRoot: false } : {}),
+        });
         if (!root) {
             return;
         }
         const interactive = isInteractive(options);
+        // Archived-task linting is its own scope: it checks task completion of
+        // already-archived changes, not delta specs (whose operations are already
+        // applied). Handled before the other bulk flags so `--archived` is explicit
+        // and never alters an existing invocation's behavior (#205).
+        if (options.archived) {
+            await this.runArchivedTaskValidation(root, {
+                json: !!options.json,
+                noInteractive: resolveNoInteractive(options),
+            });
+            return;
+        }
         // Handle bulk flags first
-        if (options.all || options.changes || options.specs) {
+        if (bulk) {
             await this.runBulkValidation(root, {
                 changes: !!options.all || !!options.changes,
                 specs: !!options.all || !!options.specs,
@@ -145,7 +163,10 @@ export class ValidateCommand {
         if (type === 'change') {
             const changeDir = path.join(root.changesDir, id);
             const start = Date.now();
-            const report = await validator.validateChangeDeltaSpecs(changeDir, { mainSpecsDir: root.specsDir });
+            const report = await validator.validateChangeDeltaSpecs(changeDir, {
+                mainSpecsDir: root.specsDir,
+                projectRoot: root.path,
+            });
             const durationMs = Date.now() - start;
             this.printReport('change', id, report, durationMs, opts.json, root);
             // Non-zero exit if invalid (keeps enriched output test semantics)
@@ -222,7 +243,10 @@ export class ValidateCommand {
             queue.push(async () => {
                 const start = Date.now();
                 const changeDir = path.join(root.changesDir, id);
-                const report = await validator.validateChangeDeltaSpecs(changeDir, { mainSpecsDir: root.specsDir });
+                const report = await validator.validateChangeDeltaSpecs(changeDir, {
+                    mainSpecsDir: root.specsDir,
+                    projectRoot: root.path,
+                });
                 const durationMs = Date.now() - start;
                 return { id, type: 'change', valid: report.valid, issues: report.issues, durationMs };
             });
@@ -322,6 +346,126 @@ export class ValidateCommand {
         }
         process.exitCode = failed > 0 ? 1 : 0;
     }
+    /**
+     * 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).
+     */
+    async listArchivedChangeIds(root) {
+        try {
+            const entries = await fs.readdir(root.archiveDir, { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    /**
+     * 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).
+     */
+    async runArchivedTaskValidation(root, opts) {
+        // List first (may throw on a real archive-read failure), then start the
+        // spinner so a thrown error never leaves a spinner spinning.
+        const ids = await this.listArchivedChangeIds(root);
+        const spinner = !opts.json && !opts.noInteractive ? ora('Validating archived changes...').start() : undefined;
+        // The archive is append-only and can hold thousands of changes; a single
+        // run resolves them all under one constant projectRoot (root.path), so
+        // memoize the schema→glob lookup to avoid re-parsing the same schema.yaml
+        // once per change. The loop is intentionally sequential: the per-change work
+        // is dominated by synchronous schema/config resolution, which a promise pool
+        // cannot overlap on Node's single thread — a pool would add complexity for
+        // no real gain here.
+        const schemaGlobCache = new Map();
+        const results = [];
+        let passed = 0;
+        let failed = 0;
+        for (const id of ids) {
+            const start = Date.now();
+            const issues = [];
+            try {
+                // The explicit root.path override is load-bearing: an archived change
+                // lives one directory deeper (changes/archive/<id>), so the default
+                // "../../.." projectRoot derivation would be wrong without it.
+                const progress = await getTaskProgressDetailForChange(root.archiveDir, id, root.path, schemaGlobCache);
+                // A tasks file that exists but cannot be read must fail loudly, not be
+                // silently counted as "no tasks" and pass. Report one issue per file,
+                // pathed like every other validate issue (POSIX, root-relative).
+                for (const file of progress.unreadable) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: FileSystemUtils.toPosixPath(path.relative(root.path, file)),
+                        message: 'could not read task file',
+                    });
+                }
+                const incomplete = Math.max(progress.total - progress.completed, 0);
+                if (incomplete > 0) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: 'tasks.md',
+                        message: `${incomplete} incomplete task${incomplete === 1 ? '' : 's'} (${progress.completed}/${progress.total} completed)`,
+                    });
+                }
+            }
+            catch (error) {
+                issues.push({ level: 'ERROR', path: 'tasks.md', message: error?.message || 'Unknown error' });
+            }
+            const valid = issues.length === 0;
+            if (valid)
+                passed++;
+            else
+                failed++;
+            results.push({ id, type: 'change', valid, issues, durationMs: Date.now() - start });
+        }
+        spinner?.stop();
+        const summary = {
+            totals: { items: results.length, passed, failed },
+            byType: { change: summarizeType(results, 'change') },
+        };
+        if (opts.json) {
+            const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
+            console.log(JSON.stringify(out, null, 2));
+            process.exitCode = failed > 0 ? 1 : 0;
+            return;
+        }
+        if (results.length === 0) {
+            console.log('No archived changes found.');
+            process.exitCode = 0;
+            return;
+        }
+        // Use the same `<type>/<id>` prefix bulk validation prints, so the plain
+        // output maps to the JSON `type` ('change') and stays greppable the same way.
+        for (const res of results) {
+            if (res.valid) {
+                console.log(`✓ change/${res.id}`);
+            }
+            else {
+                console.error(`✗ change/${res.id}`);
+                for (const issue of res.issues) {
+                    const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                    console.error(`  ${prefix} ${issue.message}`);
+                }
+            }
+        }
+        console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
+        process.exitCode = failed > 0 ? 1 : 0;
+    }
 }
 function summarizeType(results, type) {
     const filtered = results.filter(r => r.type === type);

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

@@ -5,6 +5,8 @@
  */
 export interface SchemasOptions {
     json?: boolean;
+    store?: string;
+    storePath?: string;
 }
 export declare function schemasCommand(options: SchemasOptions): Promise<void>;
 //# sourceMappingURL=schemas.d.ts.map

package/dist/commands/workflow/schemas.js

@@ -5,12 +5,19 @@
  */
 import chalk from 'chalk';
 import { listSchemasWithInfo } from '../../core/artifact-graph/index.js';
+import { resolveRootForCommand } from '../../core/root-selection.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
 // -----------------------------------------------------------------------------
 export async function schemasCommand(options) {
-    const projectRoot = process.cwd();
-    const schemas = listSchemasWithInfo(projectRoot);
+    const root = await resolveRootForCommand(options, {
+        json: options.json,
+        failurePayload: { schemas: [], root: null },
+    });
+    if (!root) {
+        return;
+    }
+    const schemas = listSchemasWithInfo(root.path);
     if (options.json) {
         console.log(JSON.stringify(schemas, null, 2));
         return;