@fission-ai/openspec 1.3.1 → 1.4.1

package/dist/commands/initiative.js

@@ -0,0 +1,318 @@
+import chalk from 'chalk';
+import { createInitiative, INITIATIVE_FILE_NAMES, listInitiativeViewReferences, mountInitiativesCollection, initiativeDiagnosticFromError as coreInitiativeDiagnosticFromError, resolveInitiativeViewReference as resolveCoreInitiativeViewReference, selectContextStoreForInitiative, formatContextStoreSelector, } from '../core/collections/initiatives/index.js';
+export class InitiativeCliError extends Error {
+    diagnostic;
+    constructor(message, code, options = {}) {
+        super(message);
+        this.diagnostic = {
+            severity: 'error',
+            code,
+            message,
+            ...options,
+        };
+    }
+}
+function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function initiativeDiagnosticFromError(error) {
+    if (error instanceof InitiativeCliError) {
+        return error.diagnostic;
+    }
+    return coreInitiativeDiagnosticFromError(error);
+}
+function appendDiagnostic(payload, diagnostic) {
+    return {
+        ...payload,
+        status: [...payload.status, diagnostic],
+    };
+}
+function requireNonBlankOption(value, flagName, target, code) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new InitiativeCliError(`Pass --${flagName} <value>.`, code, {
+            target,
+            fix: `openspec initiative create <id> --${flagName} <value>`,
+        });
+    }
+    return value.trim();
+}
+function requireInitiativeId(id, commandName) {
+    if (id === undefined || id.trim().length === 0) {
+        throw new InitiativeCliError('Pass an initiative id.', 'initiative_id_required', {
+            target: 'initiative.id',
+            fix: `openspec initiative ${commandName} <id>`,
+        });
+    }
+    return id.trim();
+}
+function toContextStoreOutput(selected) {
+    return {
+        id: selected.id,
+        root: selected.root,
+        source: selected.source,
+    };
+}
+function toInitiativeOutput(selected, state) {
+    const collection = mountInitiativesCollection(selected.root);
+    return {
+        ...state,
+        store: selected.id,
+        root: collection.resolvePath(state.id),
+        store_path: collection.toStorePath(state.id),
+    };
+}
+function listedInitiativeToOutput(initiative) {
+    return {
+        version: 1,
+        id: initiative.id,
+        title: initiative.title,
+        summary: initiative.summary,
+        status: initiative.status,
+        created: initiative.created,
+        owners: initiative.owners,
+        metadata: initiative.metadata,
+        store: initiative.store,
+        root: initiative.root,
+        store_path: initiative.storePath,
+    };
+}
+function initiativeReferenceToShowOutput(reference) {
+    return {
+        version: 1,
+        id: reference.id,
+        title: reference.title,
+        summary: reference.summary,
+        created: reference.created,
+        root: reference.root,
+        store_path: reference.storePath,
+        metadata_path: reference.metadataPath,
+    };
+}
+function printCreateHuman(payload) {
+    if (!payload.context_store || !payload.initiative) {
+        return;
+    }
+    console.log(chalk.green('Created initiative'));
+    console.log(`ID: ${payload.initiative.id}`);
+    console.log(`Title: ${payload.initiative.title}`);
+    console.log(`Status: ${payload.initiative.status}`);
+    console.log(`Context store: ${payload.context_store.id}`);
+    console.log(`Location: ${payload.initiative.root}`);
+    console.log('');
+    console.log(`Created files (${payload.created_files.length}):`);
+    for (const fileName of payload.created_files) {
+        console.log(`  - ${fileName}`);
+    }
+    console.log('');
+    console.log('Next useful commands:');
+    console.log(`  openspec initiative list ${formatContextStoreSelector(payload.context_store)}`);
+}
+function printTableHeader(includeStore) {
+    const idHeader = 'ID'.padEnd(22);
+    const storeHeader = includeStore ? `${'Store'.padEnd(12)}` : '';
+    console.log(`${idHeader}${storeHeader}Title`);
+}
+function printInitiativeRow(initiative, includeStore) {
+    const id = initiative.id.padEnd(22);
+    const store = includeStore ? `${initiative.store.padEnd(12)}` : '';
+    console.log(`${id}${store}${initiative.title}`);
+}
+function printListStatuses(statuses) {
+    if (statuses.length === 0) {
+        return;
+    }
+    console.log('');
+    for (const status of statuses) {
+        console.log(status.message);
+        if (status.fix) {
+            console.log(`Run: ${status.fix}`);
+        }
+    }
+}
+function printListHuman(payload) {
+    if (payload.context_store) {
+        console.log(`OpenSpec initiatives in ${payload.context_store.id} (${payload.initiatives.length})`);
+        if (payload.initiatives.length === 0) {
+            console.log('');
+            console.log(`No initiatives found in ${payload.context_store.id}.`);
+            console.log('');
+            console.log(`Location: ${payload.context_store.root}`);
+            return;
+        }
+        console.log('');
+        printTableHeader(false);
+        for (const initiative of payload.initiatives) {
+            printInitiativeRow(initiative, false);
+        }
+        console.log('');
+        console.log(`Location: ${payload.context_store.root}`);
+        return;
+    }
+    if (payload.context_stores.length === 0) {
+        console.log('No initiatives found because no context stores are registered.');
+        return;
+    }
+    if (payload.initiatives.length === 0) {
+        console.log('No initiatives found across registered context stores.');
+        printListStatuses(payload.status);
+        return;
+    }
+    console.log(`OpenSpec initiatives (${payload.initiatives.length} across ${payload.context_stores.length} stores)`);
+    console.log('');
+    printTableHeader(true);
+    for (const initiative of payload.initiatives) {
+        printInitiativeRow(initiative, true);
+    }
+    printListStatuses(payload.status);
+}
+function printShowHuman(payload) {
+    if (!payload.context_store || !payload.initiative) {
+        return;
+    }
+    console.log(`OpenSpec initiative: ${payload.initiative.title}`);
+    console.log('');
+    console.log(`ID: ${payload.initiative.id}`);
+    console.log(`Summary: ${payload.initiative.summary}`);
+    console.log(`Context store: ${payload.context_store.id}`);
+    console.log(`Location: ${payload.initiative.root}`);
+    console.log(`Metadata: ${payload.initiative.metadata_path}`);
+}
+function printDiagnosticMatches(diagnostic) {
+    const matches = diagnostic.details?.matches ?? [];
+    if (matches.length === 0) {
+        return;
+    }
+    console.error('');
+    console.error(diagnostic.code === 'initiative_lookup_incomplete' ? 'Partial matches:' : 'Matches:');
+    for (const match of matches) {
+        console.error(`  ${match.context_store.id.padEnd(12)}${match.initiative.root}`);
+    }
+}
+class InitiativeCommand {
+    async create(id, options = {}) {
+        try {
+            const initiativeId = requireInitiativeId(id, 'create');
+            const title = requireNonBlankOption(options.title, 'title', 'initiative.title', 'initiative_title_required');
+            const summary = requireNonBlankOption(options.summary, 'summary', 'initiative.summary', 'initiative_summary_required');
+            const selected = await selectContextStoreForInitiative(options, 'create');
+            const collection = mountInitiativesCollection(selected.root);
+            const state = await createInitiative({
+                collection,
+                id: initiativeId,
+                title,
+                summary,
+            });
+            const payload = {
+                context_store: toContextStoreOutput(selected),
+                initiative: toInitiativeOutput(selected, state),
+                created_files: [...INITIATIVE_FILE_NAMES],
+                status: [],
+            };
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            printCreateHuman(payload);
+        }
+        catch (error) {
+            this.handleFailure(options.json, { context_store: null, initiative: null, created_files: [], status: [] }, error);
+        }
+    }
+    async list(options = {}) {
+        try {
+            const payload = await this.buildListPayload(options);
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            printListHuman(payload);
+        }
+        catch (error) {
+            this.handleFailure(options.json, { context_store: null, context_stores: [], initiatives: [], status: [] }, error);
+        }
+    }
+    async show(id, options = {}) {
+        try {
+            const initiativeId = requireInitiativeId(id, 'show');
+            const payload = await this.buildShowPayload(initiativeId, options);
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            printShowHuman(payload);
+        }
+        catch (error) {
+            this.handleFailure(options.json, { context_store: null, initiative: null, status: [] }, error);
+        }
+    }
+    async buildListPayload(options) {
+        const listed = await listInitiativeViewReferences(options);
+        const contextStores = listed.contextStores.map((store) => ({
+            context_store: toContextStoreOutput(store.contextStore),
+            initiatives: store.initiatives.map(listedInitiativeToOutput),
+            status: store.status,
+        }));
+        return {
+            context_store: listed.contextStore ? toContextStoreOutput(listed.contextStore) : null,
+            context_stores: contextStores,
+            initiatives: listed.initiatives.map(listedInitiativeToOutput),
+            status: listed.status,
+        };
+    }
+    async buildShowPayload(initiativeId, options) {
+        const reference = await resolveCoreInitiativeViewReference(initiativeId, options);
+        return {
+            context_store: {
+                id: reference.store,
+                root: reference.storeRoot,
+            },
+            initiative: initiativeReferenceToShowOutput(reference),
+            status: [],
+        };
+    }
+    handleFailure(json, payload, error) {
+        const diagnostic = initiativeDiagnosticFromError(error);
+        if (json) {
+            printJson(appendDiagnostic(payload, diagnostic));
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`Error: ${diagnostic.message}`);
+        printDiagnosticMatches(diagnostic);
+        if (diagnostic.fix) {
+            console.error(`Fix: ${diagnostic.fix}`);
+        }
+        process.exitCode = 1;
+    }
+}
+function addContextStoreSelectorOptions(command) {
+    return command
+        .option('--store <id>', 'Context store id from the local context-store registry')
+        .option('--store-path <path>', 'Existing local context store root')
+        .option('--json', 'Output as JSON');
+}
+export function registerInitiativeCommand(program) {
+    const initiativeCommand = new InitiativeCommand();
+    const initiative = program
+        .command('initiative')
+        .description('Create and list coordinated initiatives');
+    addContextStoreSelectorOptions(initiative
+        .command('create [id]')
+        .description('Create an initiative in a context store')
+        .option('--title <title>', 'Initiative title')
+        .option('--summary <summary>', 'Initiative summary')).action(async (id, options) => {
+        await initiativeCommand.create(id, options);
+    });
+    addContextStoreSelectorOptions(initiative
+        .command('show <id>')
+        .description('Show where an initiative lives and how to read it')).action(async (id, options) => {
+        await initiativeCommand.show(id, options);
+    });
+    addContextStoreSelectorOptions(initiative
+        .command('list')
+        .alias('ls')
+        .description('List initiatives across registered context stores')).action(async (options) => {
+        await initiativeCommand.list(options);
+    });
+}
+//# sourceMappingURL=initiative.js.map

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

@@ -13,5 +13,7 @@ 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,5 +8,6 @@ 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/initiative-link.d.ts

@@ -0,0 +1,24 @@
+import type { PlanningHome } from '../../core/planning-home.js';
+import { type InitiativeLinkReference } from '../../core/collections/initiatives/index.js';
+export interface ChangeCommandStatus {
+    severity: 'error' | 'warning';
+    code: string;
+    message: string;
+    target?: string;
+    fix?: string;
+    details?: unknown;
+}
+export interface InitiativeSelectorOptions {
+    initiative?: string;
+    store?: string;
+    storePath?: string;
+}
+export declare const REPO_LOCAL_INITIATIVE_LINK_ERROR = "Initiative links are supported only for repo-local changes. Run this command from the repo that owns the implementation plan.";
+export declare function printJson(payload: unknown): void;
+export declare function statusFromError(error: unknown): ChangeCommandStatus;
+export declare function assertInitiativeSelectorsHaveReference(options: InitiativeSelectorOptions): void;
+export declare function assertInitiativeReference(value: string | undefined): asserts value is string;
+export declare function assertRepoLocalInitiativeLinkPlanningHome(planningHome: PlanningHome): void;
+export declare function formatInitiativeLink(initiative: InitiativeLinkReference): string;
+export declare function sameInitiativeLink(left: InitiativeLinkReference | undefined, right: InitiativeLinkReference): boolean;
+//# sourceMappingURL=initiative-link.d.ts.map

package/dist/commands/workflow/initiative-link.js

@@ -0,0 +1,47 @@
+import { InitiativeResolutionError, } from '../../core/collections/initiatives/index.js';
+export const REPO_LOCAL_INITIATIVE_LINK_ERROR = 'Initiative links are supported only for repo-local changes. Run this command from the repo that owns the implementation plan.';
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function statusFromError(error) {
+    if (error instanceof InitiativeResolutionError) {
+        return {
+            severity: 'error',
+            code: error.code,
+            message: error.message,
+            ...(error.target ? { target: error.target } : {}),
+            ...(error.fix ? { fix: error.fix } : {}),
+            ...(error.details ? { details: error.details } : {}),
+        };
+    }
+    return {
+        severity: 'error',
+        code: 'change_error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+export function assertInitiativeSelectorsHaveReference(options) {
+    if (!options.initiative && (options.store !== undefined || options.storePath !== undefined)) {
+        throw new Error('Pass --initiative when using --store or --store-path.');
+    }
+    if (options.initiative !== undefined && options.initiative.trim().length === 0) {
+        throw new Error('Pass --initiative <id> to link a change to an initiative.');
+    }
+}
+export function assertInitiativeReference(value) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new Error('Pass --initiative <id> to set a change initiative link.');
+    }
+}
+export function assertRepoLocalInitiativeLinkPlanningHome(planningHome) {
+    if (planningHome.kind === 'workspace') {
+        throw new Error(REPO_LOCAL_INITIATIVE_LINK_ERROR);
+    }
+}
+export function formatInitiativeLink(initiative) {
+    return `${initiative.store}/${initiative.id}`;
+}
+export function sameInitiativeLink(left, right) {
+    return left?.store === right.store && left.id === right.id;
+}
+//# sourceMappingURL=initiative-link.js.map

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

@@ -23,7 +23,7 @@ export declare function printInstructionsText(instructions: ArtifactInstructions
  * 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): Promise<ApplyInstructions>;
+export declare function generateApplyInstructions(projectRoot: string, changeName: string, schemaName?: string, planningHome?: import("../../core/planning-home.js").PlanningHome): 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,6 +8,7 @@ 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 { validateChangeExists, validateSchemaExists, } from './shared.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
@@ -15,14 +16,18 @@ import { validateChangeExists, validateSchemaExists, } from './shared.js';
 export async function instructionsCommand(artifactId, options) {
     const spinner = options.json ? undefined : ora('Generating instructions...').start();
     try {
-        const projectRoot = process.cwd();
-        const changeName = await validateChangeExists(options.change, projectRoot);
+        const planningHome = resolveCurrentPlanningHomeSync();
+        const projectRoot = planningHome.root;
+        const changeName = await validateChangeExists(options.change, projectRoot, planningHome.changesDir);
         // Validate schema if explicitly provided
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
         // loadChangeContext will auto-detect schema from metadata if not provided
-        const context = loadChangeContext(projectRoot, changeName, options.schema);
+        const context = loadChangeContext(projectRoot, changeName, options.schema, {
+            changeDir: getChangeDir(planningHome, changeName),
+            planningHome,
+        });
         if (!artifactId) {
             spinner?.stop();
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
@@ -49,10 +54,14 @@ export async function instructionsCommand(artifactId, options) {
     }
 }
 export function printInstructionsText(instructions, isBlocked) {
-    const { artifactId, changeName, schemaName, changeDir, outputPath, description, instruction, context, rules, template, dependencies, unlocks, } = instructions;
+    const { artifactId, changeName, schemaName, changeDir, initiative, 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);
@@ -104,7 +113,7 @@ export function printInstructionsText(instructions, isBlocked) {
     }
     // Output location
     console.log('<output>');
-    console.log(`Write to: ${path.join(changeDir, outputPath)}`);
+    console.log(`Write to: ${resolvedOutputPath}`);
     console.log('</output>');
     console.log();
     // Instruction (guidance)
@@ -166,9 +175,12 @@ 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) {
+export async function generateApplyInstructions(projectRoot, changeName, schemaName, planningHome = resolveCurrentPlanningHomeSync({ startPath: projectRoot })) {
     // loadChangeContext will auto-detect schema from metadata if not provided
-    const context = loadChangeContext(projectRoot, changeName, schemaName);
+    const context = loadChangeContext(projectRoot, changeName, schemaName, {
+        changeDir: getChangeDir(planningHome, changeName),
+        planningHome,
+    });
     const changeDir = context.changeDir;
     // Get the full schema to access the apply phase configuration
     const schema = resolveSchema(context.schemaName, projectRoot);
@@ -245,6 +257,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         changeName,
         changeDir,
         schemaName: context.schemaName,
+        ...(context.initiative ? { initiative: context.initiative } : {}),
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
@@ -256,14 +269,15 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
 export async function applyInstructionsCommand(options) {
     const spinner = options.json ? undefined : ora('Generating apply instructions...').start();
     try {
-        const projectRoot = process.cwd();
-        const changeName = await validateChangeExists(options.change, projectRoot);
+        const planningHome = resolveCurrentPlanningHomeSync();
+        const projectRoot = planningHome.root;
+        const changeName = await validateChangeExists(options.change, projectRoot, planningHome.changesDir);
         // 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);
+        const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, planningHome);
         spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify(instructions, null, 2));
@@ -277,9 +291,12 @@ export async function applyInstructionsCommand(options) {
     }
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+    const { changeName, schemaName, initiative, 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();
     // Warning for blocked state
     if (state === 'blocked' && missingArtifacts) {

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

@@ -5,7 +5,13 @@
  */
 export interface NewChangeOptions {
     description?: string;
+    goal?: string;
+    areas?: string;
     schema?: string;
+    initiative?: string;
+    store?: string;
+    storePath?: string;
+    json?: boolean;
 }
 export declare function newChangeCommand(name: string | undefined, options: NewChangeOptions): Promise<void>;
 //# sourceMappingURL=new-change.d.ts.map