@fission-ai/openspec 1.4.1 → 1.5.0

package/dist/commands/validate.js

@@ -1,15 +1,20 @@
 import ora from 'ora';
 import path from 'path';
 import { Validator } from '../core/validation/validator.js';
+import { resolveRootForCommand, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../core/root-selection.js';
 import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
 import { nearestMatches } from '../utils/match.js';
 export class ValidateCommand {
     async execute(itemName, options = {}) {
+        const root = await resolveRootForCommand(options, { json: options.json });
+        if (!root) {
+            return;
+        }
         const interactive = isInteractive(options);
         // Handle bulk flags first
         if (options.all || options.changes || options.specs) {
-            await this.runBulkValidation({
+            await this.runBulkValidation(root, {
                 changes: !!options.all || !!options.changes,
                 specs: !!options.all || !!options.specs,
             }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
@@ -18,16 +23,16 @@ export class ValidateCommand {
         // No item and no flags
         if (!itemName) {
             if (interactive) {
-                await this.runInteractiveSelector({ strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
+                await this.runInteractiveSelector(root, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
                 return;
             }
-            this.printNonInteractiveHint();
+            this.printNonInteractiveHint(root);
             process.exitCode = 1;
             return;
         }
         // Direct item validation with type detection or override
         const typeOverride = this.normalizeType(options.type);
-        await this.validateDirectItem(itemName, { typeOverride, strict: !!options.strict, json: !!options.json });
+        await this.validateDirectItem(root, itemName, { typeOverride, strict: !!options.strict, json: !!options.json });
     }
     normalizeType(value) {
         if (!value)
@@ -37,7 +42,7 @@ export class ValidateCommand {
             return v;
         return undefined;
     }
-    async runInteractiveSelector(opts) {
+    async runInteractiveSelector(root, opts) {
         const { select } = await import('@inquirer/prompts');
         const choice = await select({
             message: 'What would you like to validate?',
@@ -49,13 +54,13 @@ export class ValidateCommand {
             ],
         });
         if (choice === 'all')
-            return this.runBulkValidation({ changes: true, specs: true }, opts);
+            return this.runBulkValidation(root, { changes: true, specs: true }, opts);
         if (choice === 'changes')
-            return this.runBulkValidation({ changes: true, specs: false }, opts);
+            return this.runBulkValidation(root, { changes: true, specs: false }, opts);
         if (choice === 'specs')
-            return this.runBulkValidation({ changes: false, specs: true }, opts);
+            return this.runBulkValidation(root, { changes: false, specs: true }, opts);
         // one
-        const [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+        const [changes, specs] = await Promise.all([getActiveChangeIds(root.path), getSpecIds(root.path)]);
         const items = [];
         items.push(...changes.map(id => ({ name: `change/${id}`, value: { type: 'change', id } })));
         items.push(...specs.map(id => ({ name: `spec/${id}`, value: { type: 'spec', id } })));
@@ -65,59 +70,85 @@ export class ValidateCommand {
             return;
         }
         const picked = await select({ message: 'Pick an item', choices: items });
-        await this.validateByType(picked.type, picked.id, opts);
+        await this.validateByType(root, picked.type, picked.id, opts);
     }
-    printNonInteractiveHint() {
+    printNonInteractiveHint(root) {
         console.error('Nothing to validate. Try one of:');
-        console.error('  openspec validate --all');
-        console.error('  openspec validate --changes');
-        console.error('  openspec validate --specs');
-        console.error('  openspec validate <item-name>');
+        console.error(`  ${withStoreFlag(root, 'openspec validate --all')}`);
+        console.error(`  ${withStoreFlag(root, 'openspec validate --changes')}`);
+        console.error(`  ${withStoreFlag(root, 'openspec validate --specs')}`);
+        console.error(`  ${withStoreFlag(root, 'openspec validate <item-name>')}`);
         console.error('Or run in an interactive terminal.');
     }
-    async validateDirectItem(itemName, opts) {
-        const [changes, specs] = await Promise.all([getActiveChangeIds(), getSpecIds()]);
+    async validateDirectItem(root, itemName, opts) {
+        const [changes, specs] = await Promise.all([getActiveChangeIds(root.path), getSpecIds(root.path)]);
         const isChange = changes.includes(itemName);
         const isSpec = specs.includes(itemName);
         const type = opts.typeOverride ?? (isChange ? 'change' : isSpec ? 'spec' : undefined);
         if (!type) {
-            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 (opts.json) {
+                console.log(JSON.stringify({ status: [{ severity: 'error', code: 'unknown_item', message }] }, null, 2));
+            }
+            else {
+                console.error(message);
+            }
             process.exitCode = 1;
             return;
         }
         if (!opts.typeOverride && isChange && isSpec) {
+            if (opts.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 validate / openspec spec validate');
+            // 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 validate / openspec spec validate');
+            }
             process.exitCode = 1;
             return;
         }
-        await this.validateByType(type, itemName, opts);
+        await this.validateByType(root, type, itemName, opts);
     }
-    async validateByType(type, id, opts) {
+    async validateByType(root, type, id, opts) {
         const validator = new Validator(opts.strict);
         if (type === 'change') {
-            const changeDir = path.join(process.cwd(), 'openspec', 'changes', id);
+            const changeDir = path.join(root.changesDir, id);
             const start = Date.now();
             const report = await validator.validateChangeDeltaSpecs(changeDir);
             const durationMs = Date.now() - start;
-            this.printReport('change', id, report, durationMs, opts.json);
+            this.printReport('change', id, report, durationMs, opts.json, root);
             // Non-zero exit if invalid (keeps enriched output test semantics)
             process.exitCode = report.valid ? 0 : 1;
             return;
         }
-        const file = path.join(process.cwd(), 'openspec', 'specs', id, 'spec.md');
+        const file = path.join(root.specsDir, id, 'spec.md');
         const start = Date.now();
         const report = await validator.validateSpec(file);
         const durationMs = Date.now() - start;
-        this.printReport('spec', id, report, durationMs, opts.json);
+        this.printReport('spec', id, report, durationMs, opts.json, root);
         process.exitCode = report.valid ? 0 : 1;
     }
-    printReport(type, id, report, durationMs, json) {
+    printReport(type, id, report, durationMs, json, root) {
         if (json) {
-            const out = { items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }], summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } }, version: '1.0' };
+            const out = { items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }], summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } }, version: '1.0', root: toRootOutput(root) };
             console.log(JSON.stringify(out, null, 2));
             return;
         }
@@ -131,15 +162,15 @@ export class ValidateCommand {
                 const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
                 console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
             }
-            this.printNextSteps(type);
+            this.printNextSteps(type, id, root);
         }
     }
-    printNextSteps(type) {
+    printNextSteps(type, id, root) {
         const bullets = [];
         if (type === 'change') {
             bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
             bullets.push('- Each requirement MUST include at least one #### Scenario: block');
-            bullets.push('- Debug parsed deltas: openspec change show <id> --json --deltas-only');
+            bullets.push(`- Debug parsed deltas: ${withStoreFlag(root, `openspec show ${id} --json --deltas-only`)}`);
         }
         else {
             bullets.push('- Ensure spec includes ## Purpose and ## Requirements sections');
@@ -149,11 +180,11 @@ export class ValidateCommand {
         console.error('Next steps:');
         bullets.forEach(b => console.error(`  ${b}`));
     }
-    async runBulkValidation(scope, opts) {
+    async runBulkValidation(root, scope, opts) {
         const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
         const [changeIds, specIds] = await Promise.all([
-            scope.changes ? getActiveChangeIds() : Promise.resolve([]),
-            scope.specs ? getSpecIds() : Promise.resolve([]),
+            scope.changes ? getActiveChangeIds(root.path) : Promise.resolve([]),
+            scope.specs ? getSpecIds(root.path) : Promise.resolve([]),
         ]);
         const DEFAULT_CONCURRENCY = 6;
         const maxSuggestions = 5; // used by nearestMatches
@@ -163,7 +194,7 @@ export class ValidateCommand {
         for (const id of changeIds) {
             queue.push(async () => {
                 const start = Date.now();
-                const changeDir = path.join(process.cwd(), 'openspec', 'changes', id);
+                const changeDir = path.join(root.changesDir, id);
                 const report = await validator.validateChangeDeltaSpecs(changeDir);
                 const durationMs = Date.now() - start;
                 return { id, type: 'change', valid: report.valid, issues: report.issues, durationMs };
@@ -172,7 +203,7 @@ export class ValidateCommand {
         for (const id of specIds) {
             queue.push(async () => {
                 const start = Date.now();
-                const file = path.join(process.cwd(), 'openspec', 'specs', id, 'spec.md');
+                const file = path.join(root.specsDir, id, 'spec.md');
                 const report = await validator.validateSpec(file);
                 const durationMs = Date.now() - start;
                 return { id, type: 'spec', valid: report.valid, issues: report.issues, durationMs };
@@ -188,7 +219,7 @@ export class ValidateCommand {
                 },
             };
             if (opts.json) {
-                const out = { items: [], summary, version: '1.0' };
+                const out = { items: [], summary, version: '1.0', root: toRootOutput(root) };
                 console.log(JSON.stringify(out, null, 2));
             }
             else {
@@ -245,7 +276,7 @@ export class ValidateCommand {
             },
         };
         if (opts.json) {
-            const out = { items: results, summary, version: '1.0' };
+            const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
             console.log(JSON.stringify(out, null, 2));
         }
         else {
@@ -256,6 +287,11 @@ export class ValidateCommand {
                     console.error(`✗ ${res.type}/${res.id}`);
             }
             console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
+            const firstFailure = results.find((res) => !res.valid);
+            if (firstFailure) {
+                const storeFlag = isStoreSelectedRoot(root) ? ` --store ${root.storeId}` : '';
+                console.log(`Details: openspec validate ${firstFailure.id} --type ${firstFailure.type}${storeFlag}`);
+            }
         }
         process.exitCode = failed > 0 ? 1 : 0;
     }

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

@@ -13,7 +13,5 @@ export { schemasCommand } from './schemas.js';
 export type { SchemasOptions } from './schemas.js';
 export { newChangeCommand } from './new-change.js';
 export type { NewChangeOptions } from './new-change.js';
-export { setChangeCommand } from './set-change.js';
-export type { SetChangeOptions } from './set-change.js';
 export { DEFAULT_SCHEMA } from './shared.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/workflow/index.js

@@ -8,6 +8,5 @@ export { instructionsCommand, applyInstructionsCommand } from './instructions.js
 export { templatesCommand } from './templates.js';
 export { schemasCommand } from './schemas.js';
 export { newChangeCommand } from './new-change.js';
-export { setChangeCommand } from './set-change.js';
 export { DEFAULT_SCHEMA } from './shared.js';
 //# sourceMappingURL=index.js.map

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

@@ -5,25 +5,35 @@
  * Includes both artifact instructions and apply instructions.
  */
 import { type ArtifactInstructions } from '../../core/artifact-graph/index.js';
+import { type PlanningHome } from '../../core/planning-home.js';
+import { type ReferenceIndexEntry } from '../../core/references.js';
 import { type ApplyInstructions } from './shared.js';
 export interface InstructionsOptions {
     change?: string;
     schema?: string;
+    store?: string;
+    storePath?: string;
     json?: boolean;
 }
 export interface ApplyInstructionsOptions {
     change?: string;
     schema?: string;
+    store?: string;
+    storePath?: string;
     json?: boolean;
 }
 export declare function instructionsCommand(artifactId: string | undefined, options: InstructionsOptions): Promise<void>;
 export declare function printInstructionsText(instructions: ArtifactInstructions, isBlocked: boolean): void;
+export interface GenerateApplyInstructionsOptions {
+    planningHome?: PlanningHome;
+    references?: ReferenceIndexEntry[];
+}
 /**
  * Generates apply instructions for implementing tasks from a change.
  * Schema-aware: reads apply phase configuration from schema to determine
  * required artifacts, tracking file, and instruction.
  */
-export declare function generateApplyInstructions(projectRoot: string, changeName: string, schemaName?: string, planningHome?: import("../../core/planning-home.js").PlanningHome): Promise<ApplyInstructions>;
+export declare function generateApplyInstructions(projectRoot: string, changeName: string, schemaName?: string, options?: GenerateApplyInstructionsOptions): Promise<ApplyInstructions>;
 export declare function applyInstructionsCommand(options: ApplyInstructionsOptions): Promise<void>;
 export declare function printApplyInstructionsText(instructions: ApplyInstructions): void;
 //# sourceMappingURL=instructions.d.ts.map

package/dist/commands/workflow/instructions.js

@@ -8,17 +8,49 @@ import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
 import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
-import { getChangeDir, resolveCurrentPlanningHomeSync } from '../../core/planning-home.js';
+import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
+import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
+import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedStoresSection, } from '../../core/references.js';
+import { readRegistrySnapshot } from '../../core/store/registry.js';
+import { readProjectConfig } from '../../core/project-config.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
+/**
+ * Reads the resolved root's config once, assembles the referenced-store
+ * index when references are declared, and resolves the config path for
+ * fix text. Shared by both instruction surfaces.
+ */
+async function loadRootConfigContext(root) {
+    // readProjectConfig never throws: missing/unparseable configs are null.
+    const projectConfig = readProjectConfig(root.path);
+    // One registry read serves every relationship consumer in this
+    // output so it never carries a torn snapshot.
+    const snapshot = await readRegistrySnapshot();
+    const registryEntries = snapshot.entries;
+    const declared = projectConfig?.references ?? [];
+    const index = declared.length > 0
+        ? await assembleReferenceIndex({ references: declared, resolvedRoot: root, registryEntries })
+        : [];
+    // Omitted, not empty: an index emptied by self-reference omission must
+    // look identical to an undeclared one in JSON.
+    return {
+        projectConfig,
+        references: index.length > 0 ? index : undefined,
+    };
+}
 export async function instructionsCommand(artifactId, options) {
+    // Resolve (and banner) before the spinner starts so stderr stays readable.
+    const root = await resolveRootForCommand(options, { json: options.json });
+    if (!root) {
+        return;
+    }
     const spinner = options.json ? undefined : ora('Generating instructions...').start();
     try {
-        const planningHome = resolveCurrentPlanningHomeSync();
-        const projectRoot = planningHome.root;
-        const changeName = await validateChangeExists(options.change, projectRoot, planningHome.changesDir);
+        const planningHome = toPlanningHome(root);
+        const projectRoot = root.path;
+        const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
         // Validate schema if explicitly provided
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
@@ -39,11 +71,15 @@ export async function instructionsCommand(artifactId, options) {
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
             throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
         }
-        const instructions = generateInstructions(context, artifactId, projectRoot);
+        const { projectConfig, references } = await loadRootConfigContext(root);
+        const instructions = generateInstructions(context, artifactId, projectRoot, {
+            projectConfig,
+            references,
+        });
         const isBlocked = instructions.dependencies.some((d) => !d.done);
         spinner?.stop();
         if (options.json) {
-            console.log(JSON.stringify(instructions, null, 2));
+            console.log(JSON.stringify({ ...instructions, root: toRootOutput(root) }, null, 2));
             return;
         }
         printInstructionsText(instructions, isBlocked);
@@ -54,14 +90,10 @@ export async function instructionsCommand(artifactId, options) {
     }
 }
 export function printInstructionsText(instructions, isBlocked) {
-    const { artifactId, changeName, schemaName, changeDir, initiative, resolvedOutputPath, description, instruction, context, rules, template, dependencies, unlocks, } = instructions;
+    const { artifactId, changeName, schemaName, changeDir, resolvedOutputPath, description, instruction, context, rules, template, dependencies, unlocks, } = instructions;
     // Opening tag
     console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
     console.log();
-    if (initiative) {
-        console.log(`<initiative store="${initiative.store}" id="${initiative.id}" />`);
-        console.log();
-    }
     // Warning for blocked artifacts
     if (isBlocked) {
         const missing = dependencies.filter((d) => !d.done).map((d) => d.id);
@@ -85,6 +117,11 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log('</project_context>');
         console.log();
     }
+    // Referenced-store index (read-only upstream context)
+    if (instructions.references && instructions.references.length > 0) {
+        console.log(renderReferencedStoresBlock(instructions.references));
+        console.log();
+    }
     // Rules (AI constraint - do not include in output)
     if (rules && rules.length > 0) {
         console.log('<rules>');
@@ -175,7 +212,9 @@ function parseTasksFile(content) {
  * Schema-aware: reads apply phase configuration from schema to determine
  * required artifacts, tracking file, and instruction.
  */
-export async function generateApplyInstructions(projectRoot, changeName, schemaName, planningHome = resolveCurrentPlanningHomeSync({ startPath: projectRoot })) {
+export async function generateApplyInstructions(projectRoot, changeName, schemaName, options = {}) {
+    const planningHome = options.planningHome ?? resolveCurrentPlanningHomeSync({ startPath: projectRoot });
+    const references = options.references;
     // loadChangeContext will auto-detect schema from metadata if not provided
     const context = loadChangeContext(projectRoot, changeName, schemaName, {
         changeDir: getChangeDir(planningHome, changeName),
@@ -257,30 +296,39 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         changeName,
         changeDir,
         schemaName: context.schemaName,
-        ...(context.initiative ? { initiative: context.initiative } : {}),
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         instruction,
+        ...(references !== undefined ? { references } : {}),
     };
 }
 export async function applyInstructionsCommand(options) {
+    // Resolve (and banner) before the spinner starts so stderr stays readable.
+    const root = await resolveRootForCommand(options, { json: options.json });
+    if (!root) {
+        return;
+    }
     const spinner = options.json ? undefined : ora('Generating apply instructions...').start();
     try {
-        const planningHome = resolveCurrentPlanningHomeSync();
-        const projectRoot = planningHome.root;
-        const changeName = await validateChangeExists(options.change, projectRoot, planningHome.changesDir);
+        const planningHome = toPlanningHome(root);
+        const projectRoot = root.path;
+        const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
         // Validate schema if explicitly provided
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
         // generateApplyInstructions uses loadChangeContext which auto-detects schema
-        const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, planningHome);
+        const { references } = await loadRootConfigContext(root);
+        const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
+            planningHome,
+            references,
+        });
         spinner?.stop();
         if (options.json) {
-            console.log(JSON.stringify(instructions, null, 2));
+            console.log(JSON.stringify({ ...instructions, root: toRootOutput(root) }, null, 2));
             return;
         }
         printApplyInstructionsText(instructions);
@@ -291,13 +339,14 @@ export async function applyInstructionsCommand(options) {
     }
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, initiative, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
     console.log(`## Apply: ${changeName}`);
     console.log(`Schema: ${schemaName}`);
-    if (initiative) {
-        console.log(`Initiative: ${initiative.store}/${initiative.id}`);
-    }
     console.log();
+    if (instructions.references && instructions.references.length > 0) {
+        console.log(renderReferencedStoresSection(instructions.references));
+        console.log();
+    }
     // Warning for blocked state
     if (state === 'blocked' && missingArtifacts) {
         console.log('### ⚠️ Blocked');

package/dist/commands/workflow/new-change.d.ts

@@ -1,16 +1,19 @@
 /**
  * New Change Command
  *
- * Creates a new change directory with optional description and schema.
+ * Creates a new change directory with optional description and schema in the
+ * resolved OpenSpec root. `--store <id>` selects a registered store's
+ * root; initiative linking and workspace affected areas are no longer part of
+ * this command.
  */
 export interface NewChangeOptions {
     description?: string;
     goal?: string;
-    areas?: string;
     schema?: string;
-    initiative?: string;
     store?: string;
     storePath?: string;
+    initiative?: string;
+    areas?: string;
     json?: boolean;
 }
 export declare function newChangeCommand(name: string | undefined, options: NewChangeOptions): Promise<void>;