@fission-ai/openspec 1.4.1 → 1.5.0

package/dist/commands/context.js

@@ -0,0 +1,155 @@
+/**
+ * `openspec context` (slice 4.1): the working set a root's declarations
+ * describe, as an agent brief (JSON), a human listing, or an editor
+ * view (`--code-workspace`). Assembly is presentation over the Phase 3
+ * relationship data; doctor is the health surface. The only write this
+ * command can perform is the explicitly requested workspace file.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Option } from 'commander';
+import { resolveRootForCommand, } from '../core/root-selection.js';
+import { inspectRelationships } from '../core/relationship-health.js';
+import { assembleWorkingSet, buildCodeWorkspaceJson, isAvailableMember, } from '../core/working-set.js';
+import { StoreError } from '../core/store/errors.js';
+import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
+import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
+import { emitFailure, printJson } from './shared-output.js';
+import { gatherRelationshipData } from './shared-gather.js';
+const FAILURE_PAYLOAD = { root: null, members: [] };
+async function gatherWorkingSet(root) {
+    const data = await gatherRelationshipData(root);
+    // Reuse the 3.6 composition for member classification; the
+    // doctor-only wrong-turn detections and store facts are deliberately
+    // absent — doctor is the health surface.
+    const health = inspectRelationships({
+        root,
+        rootHealthy: data.rootInspection.healthy,
+        rootStatus: data.rootInspection.diagnostics,
+        referenceEntries: data.referenceEntries,
+        registryUnreadable: data.registrySnapshot.unreadable,
+    });
+    return {
+        workingSet: assembleWorkingSet({
+            root,
+            referenceEntries: data.referenceEntries,
+            topLevelStatus: health.status,
+        }),
+        declaredReferenceCount: data.projectConfig?.references?.length ?? 0,
+    };
+}
+function memberLine(member) {
+    return `  ${member.id}  ${member.path}`;
+}
+function printHumanWorkingSet(workingSet, declaredReferenceCount) {
+    const rootLabel = workingSet.root.store_id ?? path.basename(workingSet.root.path);
+    console.log(`Working context for ${rootLabel} (${workingSet.root.path})`);
+    console.log('');
+    console.log('OpenSpec root');
+    console.log(`  ${rootLabel}  ${workingSet.root.path}`);
+    const availableStores = workingSet.members.filter((member) => member.role === 'referenced_store' && isAvailableMember(member));
+    const unavailable = workingSet.members.filter((member) => !isAvailableMember(member));
+    if (availableStores.length > 0) {
+        console.log('');
+        console.log('Referenced stores');
+        for (const member of availableStores) {
+            console.log(memberLine(member));
+            if (member.fetch) {
+                console.log(`    Fetch: ${member.fetch}`);
+            }
+        }
+    }
+    if (workingSet.members.length === 0) {
+        console.log('');
+        // Self-references are silently omitted from the index; an
+        // emptied-by-omission set must not claim nothing was declared.
+        console.log(declaredReferenceCount > 0
+            ? 'Declared references all resolve to this root; the working set is this root alone.'
+            : 'No references declared; the working set is this root alone.');
+    }
+    if (unavailable.length > 0 || workingSet.status.length > 0) {
+        console.log('');
+        console.log('Not available on this machine');
+        for (const member of unavailable) {
+            if (member.status.length === 0) {
+                console.log(`  - ${member.id}`);
+                continue;
+            }
+            for (const diagnostic of member.status) {
+                console.log(`  - ${member.id}: ${diagnostic.message}`);
+                if (diagnostic.fix) {
+                    console.log(`    Fix: ${diagnostic.fix}`);
+                }
+            }
+        }
+        for (const diagnostic of workingSet.status) {
+            console.log(`  Note: ${diagnostic.message}`);
+            if (diagnostic.fix) {
+                console.log(`  Fix: ${diagnostic.fix}`);
+            }
+        }
+    }
+}
+function writeCodeWorkspace(workingSet, outputPath, force) {
+    const resolved = path.resolve(outputPath);
+    if (fs.existsSync(resolved) && !force) {
+        throw new StoreError(`Refusing to overwrite ${resolved}.`, 'context_file_exists', {
+            target: 'context.output',
+            fix: `Pass --force to overwrite, or choose a different path.`,
+        });
+    }
+    const parent = path.dirname(resolved);
+    if (!fs.existsSync(parent)) {
+        throw new StoreError(`Output directory does not exist: ${parent}.`, 'context_output_dir_missing', { target: 'context.output', fix: 'Create the directory first, or choose another path.' });
+    }
+    const rootName = workingSet.root.store_id ?? path.basename(workingSet.root.path);
+    fs.writeFileSync(resolved, buildCodeWorkspaceJson(workingSet, rootName));
+    const available = workingSet.members.filter(isAvailableMember).length;
+    const skipped = workingSet.members
+        .filter((member) => !isAvailableMember(member))
+        .map((member) => member.id);
+    const summary = skipped.length > 0
+        ? `Wrote ${resolved} (${available + 1} folders; not available: ${skipped.join(', ')})`
+        : `Wrote ${resolved} (${available + 1} folders)`;
+    // stderr keeps JSON stdout pure; for humans it reads inline.
+    console.error(summary);
+}
+export function registerContextCommand(program) {
+    const description = COMMAND_REGISTRY.find((entry) => entry.name === 'context')?.description ??
+        'Print the working context for the resolved OpenSpec root';
+    program
+        .command('context')
+        .description(description)
+        .option('--store <id>', COMMON_FLAGS.store.description)
+        .addOption(new Option('--store-path <path>', 'Removed; register the store and use --store').hideHelp())
+        .option('--json', 'Output the agent brief as JSON')
+        .option('--code-workspace <path>', 'Also write a VS Code workspace file for the set')
+        .option('--force', 'Overwrite an existing --code-workspace file')
+        .action(async (options) => {
+        try {
+            const root = await resolveRootForCommand({ store: options.store, storePath: options.storePath }, { json: options.json, failurePayload: FAILURE_PAYLOAD, allowImplicitRoot: false });
+            if (!root) {
+                return;
+            }
+            const { workingSet, declaredReferenceCount } = await gatherWorkingSet(root);
+            if (options.json) {
+                // The write runs FIRST: a write failure must leave stdout
+                // holding exactly one JSON document (the failure payload).
+                if (options.codeWorkspace) {
+                    writeCodeWorkspace(workingSet, options.codeWorkspace, options.force === true);
+                }
+                printJson(workingSet);
+            }
+            else {
+                printHumanWorkingSet(workingSet, declaredReferenceCount);
+                if (options.codeWorkspace) {
+                    writeCodeWorkspace(workingSet, options.codeWorkspace, options.force === true);
+                }
+            }
+        }
+        catch (error) {
+            emitFailure(options.json, FAILURE_PAYLOAD, error, 'context_failed');
+        }
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/commands/doctor.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `openspec doctor` (slice 3.6): the root-scoped relationship-health
+ * report. Read-only — it answers "are the roots this work relates to
+ * available on this machine?" and never clones, syncs, or repairs.
+ */
+import { Command } from 'commander';
+export declare function registerDoctorCommand(program: Command): void;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.js

@@ -0,0 +1,163 @@
+/**
+ * `openspec doctor` (slice 3.6): the root-scoped relationship-health
+ * report. Read-only — it answers "are the roots this work relates to
+ * available on this machine?" and never clones, syncs, or repairs.
+ */
+import { Option } from 'commander';
+import { resolveRootForCommand, } from '../core/root-selection.js';
+import { readOptionalStoreMetadataState } from '../core/store/foundation.js';
+import { gitOriginUrl, isGitRepositoryAtRoot } from '../core/store/git.js';
+import { classifyOpenSpecDir, readProjectConfig, resolveConfigFilePath, } from '../core/project-config.js';
+import { findRepoPlanningRootSync } from '../core/planning-home.js';
+import { gatherRelationshipData } from './shared-gather.js';
+import { inspectRelationships, } from '../core/relationship-health.js';
+import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
+import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
+import { emitFailure, printJson } from './shared-output.js';
+import * as path from 'node:path';
+const FAILURE_PAYLOAD = { root: null, store: null, references: [] };
+async function gatherHealth(root) {
+    const data = await gatherRelationshipData(root);
+    const { registrySnapshot, projectConfig, referenceEntries, rootInspection, } = data;
+    const registryUnreadable = registrySnapshot.unreadable;
+    const input = {
+        root,
+        rootHealthy: rootInspection.healthy,
+        rootStatus: rootInspection.diagnostics,
+        referenceEntries,
+        registryUnreadable,
+    };
+    // Store facts for store-backed roots (explicit --store or declared).
+    // Missing/invalid metadata never reaches here: store resolution
+    // verifies identity first and fails with the existing taxonomy
+    // (recorded amendment - corrupt store.yaml is an exit-1 resolution
+    // failure, not a health finding).
+    if (root.storeId) {
+        const metadata = await readOptionalStoreMetadataState(root.path).catch(() => null);
+        // git -C walks UP the tree: probing a non-repo store nested inside
+        // another repo would record the ENCLOSING repo's origin.
+        const originUrl = (await isGitRepositoryAtRoot(root.path)) ? await gitOriginUrl(root.path) : null;
+        input.storeFacts = {
+            id: root.storeId,
+            metadataPresent: metadata !== null,
+            metadataValid: metadata !== null,
+            ...(metadata?.remote ? { canonicalRemote: metadata.remote } : {}),
+            ...(originUrl ? { originUrl } : {}),
+        };
+    }
+    // The 3.2 both-shapes wrong turn, structured — including a malformed
+    // pointer value, which the resolver is silent about on planning-shaped
+    // roots.
+    if (root.source === 'nearest') {
+        const { hasPlanningShape, pointer } = classifyOpenSpecDir(root.path);
+        if (hasPlanningShape && pointer.filePath) {
+            if (pointer.value !== undefined) {
+                input.bothShapesPointer = { value: pointer.value, filePath: pointer.filePath };
+            }
+            else if (pointer.malformed) {
+                input.malformedPointer = { filePath: pointer.filePath, reason: pointer.malformed };
+            }
+        }
+    }
+    // The 3.4-recorded inert-pointer wrong turn: the resolved root is the
+    // STORE; re-walk to the pointer directory and read ITS config.
+    if (root.source === 'declared') {
+        const pointerRoot = findRepoPlanningRootSync(process.cwd());
+        if (pointerRoot) {
+            const pointerConfig = readProjectConfig(pointerRoot);
+            const fields = [];
+            if (pointerConfig?.references?.length)
+                fields.push('references');
+            if (fields.length > 0) {
+                const filePath = resolveConfigFilePath(pointerRoot) ??
+                    path.join(pointerRoot, 'openspec', 'config.yaml');
+                input.inertPointerDeclarations = { filePath, fields };
+            }
+        }
+    }
+    return {
+        health: inspectRelationships(input),
+        declaredReferenceCount: projectConfig?.references?.length ?? 0,
+    };
+}
+function printDiagnosticLines(prefix, status) {
+    for (const entry of status) {
+        console.log(`${prefix}- ${entry.message}`);
+        if (entry.fix) {
+            console.log(`${prefix}  Fix: ${entry.fix}`);
+        }
+    }
+}
+function printEntrySection(title, entries, emptyLine, okLine, idOf) {
+    console.log('');
+    console.log(title);
+    if (entries.length === 0) {
+        console.log(`  ${emptyLine}`);
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.status.length === 0) {
+            console.log(`  - ${okLine(entry)}`);
+            continue;
+        }
+        for (const diagnostic of entry.status) {
+            console.log(`  - ${idOf(entry)}: ${diagnostic.message}`);
+            if (diagnostic.fix) {
+                console.log(`    Fix: ${diagnostic.fix}`);
+            }
+        }
+    }
+}
+function printHumanHealth(health, declaredReferenceCount) {
+    console.log('Doctor');
+    console.log('');
+    console.log('Root');
+    console.log(`  Location: ${health.root.path}`);
+    console.log(`  OpenSpec root: ${health.root.healthy ? 'ok' : 'unhealthy'}`);
+    if (health.store) {
+        const metadataNote = health.store.metadata.valid ? 'metadata ok' : 'metadata invalid';
+        console.log(`  Store: ${health.store.id} (${metadataNote})`);
+    }
+    printDiagnosticLines('  ', [...health.root.status, ...(health.store?.status ?? [])]);
+    // "(none declared)" must never lie: self-references are omitted from
+    // the index, so an emptied-by-omission list gets its own line.
+    const referencesEmptyLine = health.references.length === 0 && declaredReferenceCount > 0
+        ? '(declared references all resolve to this root)'
+        : '(none declared)';
+    printEntrySection('References', health.references, referencesEmptyLine, (entry) => `${entry.store_id}: ok${entry.root ? ` (${entry.root})` : ''}`, (entry) => entry.store_id);
+    for (const entry of health.status) {
+        console.log('');
+        console.log(`Note: ${entry.message}`);
+        if (entry.fix) {
+            console.log(`Fix: ${entry.fix}`);
+        }
+    }
+}
+export function registerDoctorCommand(program) {
+    const description = COMMAND_REGISTRY.find((entry) => entry.name === 'doctor')?.description ??
+        'Report relationship health for the resolved OpenSpec root';
+    program
+        .command('doctor')
+        .description(description)
+        .option('--store <id>', COMMON_FLAGS.store.description)
+        .addOption(new Option('--store-path <path>', 'Removed; register the store and use --store').hideHelp())
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const root = await resolveRootForCommand({ store: options.store, storePath: options.storePath }, { json: options.json, failurePayload: FAILURE_PAYLOAD, allowImplicitRoot: false });
+            if (!root) {
+                return;
+            }
+            const { health, declaredReferenceCount } = await gatherHealth(root);
+            if (options.json) {
+                printJson(health);
+                return;
+            }
+            printHumanHealth(health, declaredReferenceCount);
+        }
+        catch (error) {
+            emitFailure(options.json, FAILURE_PAYLOAD, error, 'doctor_failed');
+        }
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/shared-gather.d.ts

@@ -0,0 +1,14 @@
+import { type RegistrySnapshot } from '../core/store/registry.js';
+import { type ProjectConfig } from '../core/project-config.js';
+import { type ReferenceIndexEntry } from '../core/references.js';
+import { type OpenSpecRootInspection } from '../core/openspec-root.js';
+import type { ResolvedOpenSpecRoot } from '../core/root-selection.js';
+export interface RelationshipData {
+    registrySnapshot: RegistrySnapshot;
+    projectConfig: ProjectConfig | null;
+    storeConfigPath: string;
+    referenceEntries: ReferenceIndexEntry[];
+    rootInspection: OpenSpecRootInspection;
+}
+export declare function gatherRelationshipData(root: ResolvedOpenSpecRoot): Promise<RelationshipData>;
+//# sourceMappingURL=shared-gather.d.ts.map

package/dist/commands/shared-gather.js

@@ -0,0 +1,31 @@
+/**
+ * The relationship-data gather shared by doctor and context (4.1): one
+ * registry snapshot, the health-mode reference index, and the root
+ * inspection. Doctor layers its health-only inputs (store facts,
+ * wrong-turn detection) on top.
+ */
+import * as path from 'node:path';
+import { readRegistrySnapshot } from '../core/store/registry.js';
+import { readProjectConfig, resolveConfigFilePath, } from '../core/project-config.js';
+import { assembleReferenceIndex } from '../core/references.js';
+import { inspectOpenSpecRoot } from '../core/openspec-root.js';
+export async function gatherRelationshipData(root) {
+    const registrySnapshot = await readRegistrySnapshot();
+    const projectConfig = readProjectConfig(root.path);
+    const storeConfigPath = resolveConfigFilePath(root.path) ?? path.join(root.path, 'openspec', 'config.yaml');
+    const referenceEntries = await assembleReferenceIndex({
+        references: projectConfig?.references ?? [],
+        resolvedRoot: root,
+        includeSpecs: false,
+        registryEntries: registrySnapshot.entries,
+    });
+    const rootInspection = await inspectOpenSpecRoot(root.path);
+    return {
+        registrySnapshot,
+        projectConfig,
+        storeConfigPath,
+        referenceEntries,
+        rootInspection,
+    };
+}
+//# sourceMappingURL=shared-gather.js.map

package/dist/commands/shared-output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared JSON/failure output plumbing for command groups whose errors
+ * carry the StoreDiagnostic envelope. One definition of the failure
+ * contract: exit code 1, Error:/Fix: lines in human mode, a status
+ * array in JSON mode.
+ */
+import { type StoreDiagnostic } from '../core/store/errors.js';
+export declare function printJson(payload: unknown): void;
+export declare function asErrorMessage(error: unknown): string;
+/**
+ * @inquirer prompts reject with ExitPromptError on Ctrl-C; commands
+ * translate that to `Cancelled.` + exit 130 (third caller extracted
+ * this here in slice 7.1).
+ */
+export declare function isPromptCancellationError(error: unknown): boolean;
+export declare function asStatus(error: unknown, fallbackCode: string): StoreDiagnostic;
+export declare function emitFailure(json: boolean | undefined, payload: Record<string, unknown>, error: unknown, fallbackCode: string): void;
+//# sourceMappingURL=shared-output.d.ts.map

package/dist/commands/shared-output.js

@@ -0,0 +1,61 @@
+/**
+ * Shared JSON/failure output plumbing for command groups whose errors
+ * carry the StoreDiagnostic envelope. One definition of the failure
+ * contract: exit code 1, Error:/Fix: lines in human mode, a status
+ * array in JSON mode.
+ */
+import { StoreError } from '../core/store/errors.js';
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function asErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * @inquirer prompts reject with ExitPromptError on Ctrl-C; commands
+ * translate that to `Cancelled.` + exit 130 (third caller extracted
+ * this here in slice 7.1).
+ */
+export function isPromptCancellationError(error) {
+    return (error instanceof Error &&
+        (error.name === 'ExitPromptError' ||
+            error.message.includes('force closed the prompt with SIGINT')));
+}
+export function asStatus(error, fallbackCode) {
+    if (error instanceof StoreError) {
+        return error.diagnostic;
+    }
+    // RootSelectionError (and siblings) carry the same envelope without
+    // sharing a class hierarchy; duck-type the diagnostic once, here.
+    const diagnostic = error.diagnostic;
+    if (diagnostic && typeof diagnostic.code === 'string') {
+        return diagnostic;
+    }
+    return {
+        severity: 'error',
+        code: fallbackCode,
+        message: asErrorMessage(error),
+    };
+}
+export function emitFailure(json, payload, error, fallbackCode) {
+    // Ctrl-C in a prompt is the user's choice, not an error: every
+    // command group gets the Cancelled./130 convention through here.
+    if (!json && isPromptCancellationError(error)) {
+        console.error('Cancelled.');
+        process.exitCode = 130;
+        return;
+    }
+    const status = asStatus(error, fallbackCode);
+    if (json) {
+        const prior = Array.isArray(payload.status) ? payload.status : [];
+        printJson({ ...payload, status: [...prior, status] });
+        process.exitCode = 1;
+        return;
+    }
+    console.error(`Error: ${status.message}`);
+    if (status.fix) {
+        console.error(`Fix: ${status.fix}`);
+    }
+    process.exitCode = 1;
+}
+//# sourceMappingURL=shared-output.js.map

package/dist/commands/show.d.ts

@@ -1,14 +1,19 @@
+interface ShowExecuteOptions {
+    json?: boolean;
+    type?: string;
+    noInteractive?: boolean;
+    store?: string;
+    storePath?: string;
+    [k: string]: any;
+}
 export declare class ShowCommand {
-    execute(itemName?: string, options?: {
-        json?: boolean;
-        type?: string;
-        noInteractive?: boolean;
-        [k: string]: any;
-    }): Promise<void>;
+    execute(itemName?: string, options?: ShowExecuteOptions): Promise<void>;
     private normalizeType;
+    private delegateOptions;
     private runInteractiveByType;
     private showDirect;
     private printNonInteractiveHint;
     private warnIrrelevantFlags;
 }
+export {};
 //# sourceMappingURL=show.d.ts.map

package/dist/commands/show.js

@@ -1,5 +1,6 @@
 import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
+import { resolveRootForCommand, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../core/root-selection.js';
 import { ChangeCommand } from './change.js';
 import { SpecCommand } from './spec.js';
 import { nearestMatches } from '../utils/match.js';
@@ -7,6 +8,10 @@ const CHANGE_FLAG_KEYS = new Set(['deltasOnly', 'requirementsOnly']);
 const SPEC_FLAG_KEYS = new Set(['requirements', 'scenarios', 'requirement']);
 export class ShowCommand {
     async execute(itemName, options = {}) {
+        const root = await resolveRootForCommand(options, { json: options.json });
+        if (!root) {
+            return;
+        }
         const interactive = isInteractive(options);
         const typeOverride = this.normalizeType(options.type);
         if (!itemName) {
@@ -19,14 +24,14 @@ export class ShowCommand {
                         { name: 'Spec', value: 'spec' },
                     ],
                 });
-                await this.runInteractiveByType(type, options);
+                await this.runInteractiveByType(type, options, root);
                 return;
             }
-            this.printNonInteractiveHint();
+            this.printNonInteractiveHint(root);
             process.exitCode = 1;
             return;
         }
-        await this.showDirect(itemName, { typeOverride, options });
+        await this.showDirect(itemName, { typeOverride, options, root });
     }
     normalizeType(value) {
         if (!value)
@@ -36,78 +41,118 @@ export class ShowCommand {
             return v;
         return undefined;
     }
-    async runInteractiveByType(type, options) {
+    delegateOptions(root, options) {
+        return {
+            ...options,
+            ...(options.json ? { rootOutput: toRootOutput(root) } : {}),
+        };
+    }
+    async runInteractiveByType(type, options, root) {
         const { select } = await import('@inquirer/prompts');
         if (type === 'change') {
-            const changes = await getActiveChangeIds();
+            const changes = await getActiveChangeIds(root.path);
             if (changes.length === 0) {
                 console.error('No changes found.');
                 process.exitCode = 1;
                 return;
             }
             const picked = await select({ message: 'Pick a change', choices: changes.map(id => ({ name: id, value: id })) });
-            const cmd = new ChangeCommand();
-            await cmd.show(picked, options);
+            const cmd = new ChangeCommand(root.path);
+            await cmd.show(picked, this.delegateOptions(root, options));
             return;
         }
-        const specs = await getSpecIds();
+        const specs = await getSpecIds(root.path);
         if (specs.length === 0) {
             console.error('No specs found.');
             process.exitCode = 1;
             return;
         }
         const picked = await select({ message: 'Pick a spec', choices: specs.map(id => ({ name: id, value: id })) });
-        const cmd = new SpecCommand();
-        await cmd.show(picked, options);
+        const cmd = new SpecCommand(root.path);
+        await cmd.show(picked, this.delegateOptions(root, options));
     }
     async showDirect(itemName, params) {
+        const root = params.root;
         // Optimize lookups when type is pre-specified
         let isChange = false;
         let isSpec = false;
         let changes = [];
         let specs = [];
         if (params.typeOverride === 'change') {
-            changes = await getActiveChangeIds();
+            changes = await getActiveChangeIds(root.path);
             isChange = changes.includes(itemName);
         }
         else if (params.typeOverride === 'spec') {
-            specs = await getSpecIds();
+            specs = await getSpecIds(root.path);
             isSpec = specs.includes(itemName);
         }
         else {
-            [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+            [changes, specs] = await Promise.all([getActiveChangeIds(root.path), getSpecIds(root.path)]);
             isChange = changes.includes(itemName);
             isSpec = specs.includes(itemName);
         }
         const resolvedType = params.typeOverride ?? (isChange ? 'change' : isSpec ? 'spec' : undefined);
         if (!resolvedType) {
-            console.error(`Unknown item '${itemName}'`);
             const suggestions = nearestMatches(itemName, [...changes, ...specs]);
-            if (suggestions.length)
-                console.error(`Did you mean: ${suggestions.join(', ')}?`);
+            const message = suggestions.length
+                ? `Unknown item '${itemName}'. Did you mean: ${suggestions.join(', ')}?`
+                : `Unknown item '${itemName}'.`;
+            if (params.options.json) {
+                console.log(JSON.stringify({ status: [{ severity: 'error', code: 'unknown_item', message }] }, null, 2));
+            }
+            else {
+                console.error(message);
+            }
             process.exitCode = 1;
             return;
         }
         if (!params.typeOverride && isChange && isSpec) {
+            if (params.options.json) {
+                console.log(JSON.stringify({
+                    status: [
+                        {
+                            severity: 'error',
+                            code: 'ambiguous_item',
+                            message: `Ambiguous item '${itemName}' matches both a change and a spec.`,
+                            fix: 'Pass --type change|spec.',
+                        },
+                    ],
+                }, null, 2));
+                process.exitCode = 1;
+                return;
+            }
             console.error(`Ambiguous item '${itemName}' matches both a change and a spec.`);
-            console.error('Pass --type change|spec, or use: openspec change show / openspec spec show');
+            // The noun-form commands are cwd-based and cannot reach a selected store.
+            if (isStoreSelectedRoot(root)) {
+                console.error('Pass --type change|spec.');
+            }
+            else {
+                console.error('Pass --type change|spec, or use: openspec change show / openspec spec show');
+            }
             process.exitCode = 1;
             return;
         }
         this.warnIrrelevantFlags(resolvedType, params.options);
         if (resolvedType === 'change') {
-            const cmd = new ChangeCommand();
-            await cmd.show(itemName, params.options);
+            const cmd = new ChangeCommand(root.path);
+            await cmd.show(itemName, this.delegateOptions(root, params.options));
             return;
         }
-        const cmd = new SpecCommand();
-        await cmd.show(itemName, params.options);
+        const cmd = new SpecCommand(root.path);
+        await cmd.show(itemName, this.delegateOptions(root, params.options));
     }
-    printNonInteractiveHint() {
+    printNonInteractiveHint(root) {
         console.error('Nothing to show. Try one of:');
-        console.error('  openspec show <item>');
-        console.error('  openspec change show');
-        console.error('  openspec spec show');
+        console.error(`  ${withStoreFlag(root, 'openspec show <item>')}`);
+        if (isStoreSelectedRoot(root)) {
+            // The noun-form commands are cwd-based and cannot reach a selected store.
+            console.error(`  ${withStoreFlag(root, 'openspec show <item> --type change')}`);
+            console.error(`  ${withStoreFlag(root, 'openspec show <item> --type spec')}`);
+        }
+        else {
+            console.error('  openspec change show');
+            console.error('  openspec spec show');
+        }
         console.error('Or run in an interactive terminal.');
     }
     warnIrrelevantFlags(type, options) {