@fission-ai/openspec 1.3.1 → 1.4.1

package/dist/core/artifact-graph/instruction-loader.js

@@ -3,8 +3,10 @@ import * as path from 'node:path';
 import { getSchemaDir, resolveSchema } from './resolver.js';
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
-import { resolveSchemaForChange } from '../../utils/change-metadata.js';
+import { resolveArtifactOutputs } from './outputs.js';
+import { readChangeMetadata, resolveSchemaForChange } from '../../utils/change-metadata.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { buildActionContext, buildNextSteps, summarizeAffectedAreas, summarizePlanningHome, } from '../change-status-policy.js';
 import { readProjectConfig, validateConfigRules } from '../project-config.js';
 // Session-level cache for validation warnings (avoid repeating same warnings)
 const shownWarnings = new Set();
@@ -59,10 +61,12 @@ export function loadTemplate(schemaName, templatePath, projectRoot) {
  * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
  * @returns Change context with graph, completed set, and metadata
  */
-export function loadChangeContext(projectRoot, changeName, schemaName) {
-    const changeDir = FileSystemUtils.canonicalizeExistingPath(path.join(projectRoot, 'openspec', 'changes', changeName));
-    // Resolve schema: explicit > metadata > default
-    const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);
+export function loadChangeContext(projectRoot, changeName, schemaName, options = {}) {
+    const changeDir = FileSystemUtils.canonicalizeExistingPath(options.changeDir ?? path.join(projectRoot, 'openspec', 'changes', changeName));
+    const metadata = readChangeMetadata(changeDir, projectRoot) ?? undefined;
+    const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName, projectRoot, {
+        metadata: metadata ?? null,
+    });
     const schema = resolveSchema(resolvedSchemaName, projectRoot);
     const graph = ArtifactGraph.fromSchema(schema);
     const completed = detectCompleted(graph, changeDir);
@@ -73,6 +77,9 @@ export function loadChangeContext(projectRoot, changeName, schemaName) {
         changeName,
         changeDir,
         projectRoot,
+        ...(options.planningHome ? { planningHome: options.planningHome } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(metadata?.initiative ? { initiative: metadata.initiative } : {}),
     };
 }
 /**
@@ -130,7 +137,11 @@ export function generateInstructions(context, artifactId, projectRoot) {
         artifactId: artifact.id,
         schemaName: context.schemaName,
         changeDir: context.changeDir,
+        planningHome: summarizePlanningHome(context.planningHome),
+        ...(context.initiative ? { initiative: context.initiative } : {}),
         outputPath: artifact.generates,
+        resolvedOutputPath: path.join(context.changeDir, artifact.generates),
+        existingOutputPaths: resolveArtifactOutputs(context.changeDir, artifact.generates),
         description: artifact.description,
         instruction: artifact.instruction,
         context: configContext,
@@ -179,7 +190,13 @@ export function formatChangeStatus(context) {
     const artifacts = context.graph.getAllArtifacts();
     const ready = new Set(context.graph.getNextArtifacts(context.completed));
     const blocked = context.graph.getBlocked(context.completed);
+    const artifactPaths = {};
     const artifactStatuses = artifacts.map(artifact => {
+        artifactPaths[artifact.id] = {
+            outputPath: artifact.generates,
+            resolvedOutputPath: path.join(context.changeDir, artifact.generates),
+            existingOutputPaths: resolveArtifactOutputs(context.changeDir, artifact.generates),
+        };
         if (context.completed.has(artifact.id)) {
             return {
                 id: artifact.id,
@@ -205,11 +222,34 @@ export function formatChangeStatus(context) {
     const buildOrder = context.graph.getBuildOrder();
     const orderMap = new Map(buildOrder.map((id, idx) => [id, idx]));
     artifactStatuses.sort((a, b) => (orderMap.get(a.id) ?? 0) - (orderMap.get(b.id) ?? 0));
+    const affectedAreas = summarizeAffectedAreas({
+        planningHome: context.planningHome,
+        metadata: context.metadata,
+    });
+    const isComplete = context.graph.isComplete(context.completed);
+    const artifactIds = artifactStatuses.map((artifact) => artifact.id);
     return {
         changeName: context.changeName,
         schemaName: context.schemaName,
-        isComplete: context.graph.isComplete(context.completed),
+        planningHome: summarizePlanningHome(context.planningHome),
+        ...(context.initiative ? { initiative: context.initiative } : {}),
+        changeRoot: context.changeDir,
+        artifactPaths,
+        affectedAreas,
+        isComplete,
         applyRequires,
+        nextSteps: buildNextSteps({
+            changeName: context.changeName,
+            planningHome: context.planningHome,
+            artifactStatuses,
+            affectedAreas,
+            allArtifactsComplete: isComplete,
+        }),
+        actionContext: buildActionContext({
+            planningHome: context.planningHome,
+            projectRoot: context.projectRoot,
+            artifactIds,
+        }),
         artifacts: artifactStatuses,
     };
 }

package/dist/core/artifact-graph/types.d.ts

@@ -33,11 +33,6 @@ export declare const SchemaYamlSchema: z.ZodObject<{
 export type Artifact = z.infer<typeof ArtifactSchema>;
 export type ApplyPhase = z.infer<typeof ApplyPhaseSchema>;
 export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
-export declare const ChangeMetadataSchema: z.ZodObject<{
-    schema: z.ZodString;
-    created: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
 export type CompletedSet = Set<string>;
 export interface BlockedArtifacts {
     [artifactId: string]: string[];

package/dist/core/artifact-graph/types.js

@@ -26,18 +26,4 @@ export const SchemaYamlSchema = z.object({
     // Optional apply phase configuration (for schema-aware apply instructions)
     apply: ApplyPhaseSchema.optional(),
 });
-// Per-change metadata schema
-// Note: schema field is validated at parse time against available schemas
-// using a lazy import to avoid circular dependencies
-export const ChangeMetadataSchema = z.object({
-    // Required: which workflow schema this change uses
-    schema: z.string().min(1, { message: 'schema is required' }),
-    // Optional: creation timestamp (ISO date string)
-    created: z
-        .string()
-        .regex(/^\d{4}-\d{2}-\d{2}$/, {
-        message: 'created must be YYYY-MM-DD format',
-    })
-        .optional(),
-});
 //# sourceMappingURL=types.js.map

package/dist/core/change-metadata/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/change-metadata/index.js

@@ -0,0 +1,2 @@
+export * from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/core/change-metadata/schema.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const InitiativeLinkSchema: z.ZodObject<{
+    store: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strict>;
+export type InitiativeLink = z.infer<typeof InitiativeLinkSchema>;
+export declare const ChangeMetadataSchema: z.ZodObject<{
+    schema: z.ZodString;
+    created: z.ZodOptional<z.ZodString>;
+    goal: z.ZodOptional<z.ZodString>;
+    affected_areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    initiative: z.ZodOptional<z.ZodObject<{
+        store: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/change-metadata/schema.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+const KebabIdentifierSchema = (label) => z.string().superRefine((value, ctx) => {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `${label} must be kebab-case with lowercase letters, numbers, and single hyphen separators`,
+        });
+    }
+});
+export const InitiativeLinkSchema = z.object({
+    store: KebabIdentifierSchema('Context store id'),
+    id: KebabIdentifierSchema('Initiative id'),
+}).strict();
+// Per-change metadata schema. The schema field is validated against available
+// workflow schemas when metadata is read or written.
+export const ChangeMetadataSchema = z.object({
+    schema: z.string().min(1, { message: 'schema is required' }),
+    created: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, {
+        message: 'created must be YYYY-MM-DD format',
+    })
+        .optional(),
+    goal: z.string().min(1).optional(),
+    affected_areas: z.array(z.string().min(1)).optional(),
+    initiative: InitiativeLinkSchema.optional(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/core/change-status-policy.d.ts

@@ -0,0 +1,50 @@
+import type { ChangeMetadata } from './change-metadata/index.js';
+import type { PlanningHome } from './planning-home.js';
+export interface PlanningHomeSummary {
+    kind: 'repo' | 'workspace';
+    root: string;
+    changesDir: string;
+    defaultSchema: string;
+    workspaceName?: string;
+}
+export interface AffectedAreasSummary {
+    known: string[];
+    unresolved: boolean;
+    invalid: string[];
+}
+export interface ActionContext {
+    mode: 'repo-local' | 'workspace-planning';
+    sourceOfTruth: 'repo' | 'workspace-local';
+    planningArtifacts: string[];
+    linkedContext: Array<{
+        name: string;
+    }>;
+    allowedEditRoots: string[];
+    requiresAffectedAreaSelection: boolean;
+    constraints: string[];
+}
+export interface ChangeStatusPolicyArtifact {
+    id: string;
+    status: 'done' | 'ready' | 'blocked';
+}
+export interface AffectedAreasInput {
+    planningHome?: PlanningHome;
+    metadata?: ChangeMetadata;
+}
+export interface ChangeNextStepsInput {
+    changeName: string;
+    planningHome?: PlanningHome;
+    artifactStatuses: ChangeStatusPolicyArtifact[];
+    affectedAreas?: AffectedAreasSummary;
+    allArtifactsComplete: boolean;
+}
+export interface ActionContextInput {
+    planningHome?: PlanningHome;
+    projectRoot: string;
+    artifactIds: string[];
+}
+export declare function summarizePlanningHome(planningHome: PlanningHome | undefined): PlanningHomeSummary | undefined;
+export declare function summarizeAffectedAreas(input: AffectedAreasInput): AffectedAreasSummary | undefined;
+export declare function buildActionContext(input: ActionContextInput): ActionContext;
+export declare function buildNextSteps(input: ChangeNextStepsInput): string[];
+//# sourceMappingURL=change-status-policy.d.ts.map

package/dist/core/change-status-policy.js

@@ -0,0 +1,70 @@
+export function summarizePlanningHome(planningHome) {
+    if (!planningHome) {
+        return undefined;
+    }
+    return {
+        kind: planningHome.kind,
+        root: planningHome.root,
+        changesDir: planningHome.changesDir,
+        defaultSchema: planningHome.defaultSchema,
+        ...(planningHome.workspace ? { workspaceName: planningHome.workspace.name } : {}),
+    };
+}
+export function summarizeAffectedAreas(input) {
+    if (input.planningHome?.kind !== 'workspace') {
+        return undefined;
+    }
+    const known = Array.from(new Set(input.metadata?.affected_areas ?? [])).sort((a, b) => a.localeCompare(b));
+    const validAreas = new Set(input.planningHome.workspace?.links ?? []);
+    const invalid = known.filter((areaName) => validAreas.size > 0 && !validAreas.has(areaName));
+    return {
+        known,
+        unresolved: known.length === 0,
+        invalid,
+    };
+}
+export function buildActionContext(input) {
+    if (input.planningHome?.kind === 'workspace') {
+        return {
+            mode: 'workspace-planning',
+            sourceOfTruth: 'workspace-local',
+            planningArtifacts: input.artifactIds,
+            linkedContext: (input.planningHome.workspace?.links ?? []).map((name) => ({ name })),
+            allowedEditRoots: [],
+            requiresAffectedAreaSelection: true,
+            constraints: [
+                'Treat workspace-local planning artifacts as compatibility context for this local view.',
+                'Use initiatives for durable coordination when initiative context exists.',
+                'Treat linked repos and folders as context until an explicit edit root is selected.',
+                'Do not make implementation edits without an explicit allowed edit root.',
+            ],
+        };
+    }
+    return {
+        mode: 'repo-local',
+        sourceOfTruth: 'repo',
+        planningArtifacts: input.artifactIds,
+        linkedContext: [],
+        allowedEditRoots: [input.projectRoot],
+        requiresAffectedAreaSelection: false,
+        constraints: ['Repo-local change artifacts and implementation edits are scoped to this project.'],
+    };
+}
+export function buildNextSteps(input) {
+    const readyArtifact = input.artifactStatuses.find((artifact) => artifact.status === 'ready');
+    const steps = [];
+    if (readyArtifact) {
+        steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}" --json before writing that artifact.`);
+    }
+    else if (input.allArtifactsComplete) {
+        steps.push('All planning artifacts are complete; review tasks before implementation.');
+    }
+    if (input.planningHome?.kind === 'workspace') {
+        if (input.affectedAreas?.unresolved) {
+            steps.push('Identify affected areas in change metadata or coordination tasks as planning continues.');
+        }
+        steps.push('Select an affected area and allowed edit root before implementation edits.');
+    }
+    return steps;
+}
+//# sourceMappingURL=change-status-policy.js.map

package/dist/core/collections/index.d.ts

@@ -0,0 +1,3 @@
+export * from './runtime.js';
+export * from './initiatives/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/collections/index.js

@@ -0,0 +1,3 @@
+export * from './runtime.js';
+export * from './initiatives/index.js';
+//# sourceMappingURL=index.js.map

package/dist/core/collections/initiatives/collection.d.ts

@@ -0,0 +1,4 @@
+import { type CollectionRegistry, type MountedCollection } from '../runtime.js';
+export declare function createInitiativesCollectionRegistry(): CollectionRegistry;
+export declare function mountInitiativesCollection(storeRoot: string): MountedCollection;
+//# sourceMappingURL=collection.d.ts.map

package/dist/core/collections/initiatives/collection.js

@@ -0,0 +1,17 @@
+import { createCollectionRegistry, mountCollections, } from '../runtime.js';
+import { INITIATIVE_COLLECTION_ID } from './schema.js';
+export function createInitiativesCollectionRegistry() {
+    return createCollectionRegistry([
+        {
+            id: INITIATIVE_COLLECTION_ID,
+            mount: INITIATIVE_COLLECTION_ID,
+        },
+    ]);
+}
+export function mountInitiativesCollection(storeRoot) {
+    return mountCollections({
+        storeRoot,
+        collections: createInitiativesCollectionRegistry(),
+    }).require(INITIATIVE_COLLECTION_ID);
+}
+//# sourceMappingURL=collection.js.map

package/dist/core/collections/initiatives/index.d.ts

@@ -0,0 +1,6 @@
+export * from './collection.js';
+export * from './schema.js';
+export * from './templates.js';
+export * from './operations.js';
+export * from './resolution.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/collections/initiatives/index.js

@@ -0,0 +1,6 @@
+export * from './collection.js';
+export * from './schema.js';
+export * from './templates.js';
+export * from './operations.js';
+export * from './resolution.js';
+//# sourceMappingURL=index.js.map

package/dist/core/collections/initiatives/operations.d.ts

@@ -0,0 +1,49 @@
+import * as nodeFs from 'node:fs';
+import type { MountedCollection } from '../runtime.js';
+import { type InitiativeMetadata, type InitiativeState, type InitiativeStatus } from './schema.js';
+import { type InitiativeTemplateFile } from './templates.js';
+export interface InitiativeDirectoryEntry {
+    name: string;
+    isDirectory(): boolean;
+}
+export interface InitiativeOperationsFileSystem {
+    mkdir(dirPath: string, options: {
+        recursive?: boolean;
+    }): Promise<void>;
+    writeFile(filePath: string, content: string, options: {
+        flag?: nodeFs.OpenMode;
+    }): Promise<void>;
+    readFile(filePath: string): Promise<string>;
+    readdir(dirPath: string, options: {
+        withFileTypes: true;
+    }): Promise<readonly InitiativeDirectoryEntry[]>;
+    rm(dirPath: string, options: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+}
+export interface InitiativeOperationDependencies {
+    fileSystem?: InitiativeOperationsFileSystem;
+}
+export interface CreateInitiativeInput extends InitiativeOperationDependencies {
+    collection: MountedCollection;
+    id: string;
+    title: string;
+    summary: string;
+    status?: InitiativeStatus;
+    owners?: string[];
+    metadata?: InitiativeMetadata;
+    getCurrentDate?: () => string;
+    buildTemplateFiles?: (state: InitiativeState) => readonly InitiativeTemplateFile[];
+}
+export interface ListInitiativesInput extends InitiativeOperationDependencies {
+    collection: MountedCollection;
+}
+export interface ReadInitiativeInput extends InitiativeOperationDependencies {
+    collection: MountedCollection;
+    id: string;
+}
+export declare function createInitiative(input: CreateInitiativeInput): Promise<InitiativeState>;
+export declare function readInitiative(input: ReadInitiativeInput): Promise<InitiativeState | null>;
+export declare function listInitiatives(input: ListInitiativesInput): Promise<InitiativeState[]>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/core/collections/initiatives/operations.js

@@ -0,0 +1,175 @@
+import * as nodeFs from 'node:fs';
+import { INITIATIVE_COLLECTION_ID, INITIATIVE_FILE_NAME, parseInitiativeState, serializeInitiativeState, validateInitiativeId, } from './schema.js';
+import { buildDefaultInitiativeFiles, } from './templates.js';
+const fs = nodeFs.promises;
+const nodeFileSystem = {
+    async mkdir(dirPath, options) {
+        await fs.mkdir(dirPath, options);
+    },
+    async writeFile(filePath, content, options) {
+        await fs.writeFile(filePath, content, {
+            encoding: 'utf-8',
+            flag: options.flag ?? 'w',
+        });
+    },
+    async readFile(filePath) {
+        return fs.readFile(filePath, 'utf-8');
+    },
+    async readdir(dirPath, options) {
+        return fs.readdir(dirPath, options);
+    },
+    async rm(dirPath, options) {
+        await fs.rm(dirPath, options);
+    },
+};
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+function getFileSystem(fileSystem) {
+    return fileSystem ?? nodeFileSystem;
+}
+function isFileNotFoundError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+function isPathExistsError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'EEXIST');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertInitiativesCollection(collection) {
+    if (collection.collectionId !== INITIATIVE_COLLECTION_ID) {
+        throw new Error(`Expected mounted '${INITIATIVE_COLLECTION_ID}' collection, got '${collection.collectionId}'`);
+    }
+}
+function resolveInitiativeFilePath(collection, initiativeId, fileName) {
+    return collection.resolvePath(`${initiativeId}/${fileName}`);
+}
+function normalizeCreateState(input) {
+    return parseInitiativeState(serializeInitiativeState({
+        version: 1,
+        id: validateInitiativeId(input.id),
+        title: input.title,
+        summary: input.summary,
+        status: input.status ?? 'exploring',
+        created: (input.getCurrentDate ?? getCurrentDate)(),
+        owners: input.owners ?? [],
+        metadata: input.metadata ?? {},
+    }));
+}
+async function writeExclusiveFile(fileSystem, filePath, content) {
+    await fileSystem.writeFile(filePath, content, { flag: 'wx' });
+}
+async function cleanupCreatedInitiative(fileSystem, initiativeRoot, originalError, initiativeId) {
+    try {
+        await fileSystem.rm(initiativeRoot, { recursive: true, force: true });
+    }
+    catch (cleanupError) {
+        throw new Error(`Failed to create initiative '${initiativeId}' and cleanup failed: ${errorMessage(originalError)}; cleanup: ${errorMessage(cleanupError)}`);
+    }
+    throw new Error(`Failed to create initiative '${initiativeId}': ${errorMessage(originalError)}`);
+}
+export async function createInitiative(input) {
+    assertInitiativesCollection(input.collection);
+    const state = normalizeCreateState(input);
+    const fileSystem = getFileSystem(input.fileSystem);
+    const initiativeRoot = input.collection.resolvePath(state.id);
+    const buildTemplateFiles = input.buildTemplateFiles ?? buildDefaultInitiativeFiles;
+    try {
+        await fileSystem.mkdir(input.collection.resolvePath(), { recursive: true });
+        await fileSystem.mkdir(initiativeRoot, { recursive: false });
+    }
+    catch (error) {
+        if (isPathExistsError(error)) {
+            throw new Error(`Initiative '${state.id}' already exists at ${initiativeRoot}`);
+        }
+        throw new Error(`Failed to create initiative '${state.id}': ${errorMessage(error)}`);
+    }
+    try {
+        await writeExclusiveFile(fileSystem, resolveInitiativeFilePath(input.collection, state.id, INITIATIVE_FILE_NAME), serializeInitiativeState(state));
+        for (const templateFile of buildTemplateFiles(state)) {
+            await writeExclusiveFile(fileSystem, resolveInitiativeFilePath(input.collection, state.id, templateFile.fileName), templateFile.content);
+        }
+    }
+    catch (error) {
+        await cleanupCreatedInitiative(fileSystem, initiativeRoot, error, state.id);
+    }
+    return state;
+}
+export async function readInitiative(input) {
+    assertInitiativesCollection(input.collection);
+    const initiativeId = validateInitiativeId(input.id);
+    const fileSystem = getFileSystem(input.fileSystem);
+    const initiativeFilePath = resolveInitiativeFilePath(input.collection, initiativeId, INITIATIVE_FILE_NAME);
+    let content;
+    try {
+        content = await fileSystem.readFile(initiativeFilePath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+        throw new Error(`Invalid initiative '${initiativeId}': failed to read ${INITIATIVE_FILE_NAME}: ${errorMessage(error)}`);
+    }
+    let state;
+    try {
+        state = parseInitiativeState(content);
+    }
+    catch (error) {
+        throw new Error(`Invalid initiative '${initiativeId}': ${errorMessage(error)}`);
+    }
+    if (state.id !== initiativeId) {
+        throw new Error(`Invalid initiative '${initiativeId}': ${INITIATIVE_FILE_NAME} id '${state.id}' must match folder name`);
+    }
+    return state;
+}
+export async function listInitiatives(input) {
+    assertInitiativesCollection(input.collection);
+    const fileSystem = getFileSystem(input.fileSystem);
+    let entries;
+    try {
+        entries = await fileSystem.readdir(input.collection.resolvePath(), { withFileTypes: true });
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return [];
+        }
+        throw new Error(`Failed to list initiatives: ${errorMessage(error)}`);
+    }
+    const initiatives = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const initiativeFilePath = resolveInitiativeFilePath(input.collection, entry.name, INITIATIVE_FILE_NAME);
+        let content;
+        try {
+            content = await fileSystem.readFile(initiativeFilePath);
+        }
+        catch (error) {
+            if (isFileNotFoundError(error)) {
+                continue;
+            }
+            throw new Error(`Invalid initiative '${entry.name}': failed to read ${INITIATIVE_FILE_NAME}: ${errorMessage(error)}`);
+        }
+        let state;
+        try {
+            state = parseInitiativeState(content);
+        }
+        catch (error) {
+            throw new Error(`Invalid initiative '${entry.name}': ${errorMessage(error)}`);
+        }
+        if (state.id !== entry.name) {
+            throw new Error(`Invalid initiative '${entry.name}': ${INITIATIVE_FILE_NAME} id '${state.id}' must match folder name`);
+        }
+        initiatives.push(state);
+    }
+    return initiatives.sort((a, b) => a.id.localeCompare(b.id));
+}
+//# sourceMappingURL=operations.js.map

package/dist/core/collections/initiatives/resolution.d.ts

@@ -0,0 +1,87 @@
+import { formatContextStoreSelector, type ContextStoreSelectorOptions, type ContextStoreSelectorSource, type SelectedContextStore } from '../../context-store/index.js';
+import { type InitiativeState } from './schema.js';
+export interface InitiativeSelectorOptions extends ContextStoreSelectorOptions {
+    json?: boolean;
+}
+export type { ContextStoreSelectorSource, SelectedContextStore };
+export { formatContextStoreSelector };
+export interface InitiativeResolutionMatch {
+    context_store: {
+        id: string;
+        root: string;
+    };
+    initiative: {
+        id: string;
+        title: string;
+        root: string;
+    };
+}
+export interface InitiativeResolutionDetails extends Record<string, unknown> {
+    matches?: InitiativeResolutionMatch[];
+}
+export declare class InitiativeResolutionError extends Error {
+    readonly code: string;
+    readonly target?: string;
+    readonly fix?: string;
+    readonly details?: InitiativeResolutionDetails;
+    constructor(message: string, code: string, options?: {
+        target?: string;
+        fix?: string;
+        details?: InitiativeResolutionDetails;
+    });
+}
+export interface InitiativeViewReference {
+    store: string;
+    storeSource: ContextStoreSelectorSource;
+    storeRoot: string;
+    id: string;
+    title: string;
+    summary: string;
+    created: string;
+    root: string;
+    storePath: string;
+    metadataPath: string;
+}
+export interface ListedInitiativeReference extends InitiativeViewReference {
+    status: InitiativeState['status'];
+    owners: InitiativeState['owners'];
+    metadata: InitiativeState['metadata'];
+}
+export type InitiativeDiagnosticSeverity = 'error' | 'warning';
+export interface InitiativeDiagnostic {
+    severity: InitiativeDiagnosticSeverity;
+    code: string;
+    message: string;
+    target?: string;
+    fix?: string;
+    details?: InitiativeResolutionDetails;
+}
+export interface ContextStoreInitiativeListReference {
+    contextStore: SelectedContextStore;
+    initiatives: ListedInitiativeReference[];
+    status: InitiativeDiagnostic[];
+}
+export interface InitiativeListReferenceResult {
+    contextStore: SelectedContextStore | null;
+    contextStores: ContextStoreInitiativeListReference[];
+    initiatives: ListedInitiativeReference[];
+    status: InitiativeDiagnostic[];
+}
+export declare function initiativeDiagnosticFromError(error: unknown): InitiativeDiagnostic;
+export declare function parseInitiativeReference(reference: string | undefined, options: InitiativeSelectorOptions): {
+    initiativeId: string;
+    options: InitiativeSelectorOptions;
+};
+export declare function resolveRegisteredInitiativeContextStore(storeId: string): Promise<SelectedContextStore>;
+export declare function resolvePathInitiativeContextStore(storePath: string): Promise<SelectedContextStore>;
+export declare function selectContextStoreForInitiative(options: InitiativeSelectorOptions, commandName: 'create' | 'list' | 'show'): Promise<SelectedContextStore>;
+export declare function resolveSelectedInitiativeViewReference(selected: SelectedContextStore, initiativeId: string): Promise<InitiativeViewReference>;
+export declare function listSelectedInitiativeViewReferences(selected: SelectedContextStore): Promise<ContextStoreInitiativeListReference>;
+export declare function listInitiativeViewReferences(options?: InitiativeSelectorOptions): Promise<InitiativeListReferenceResult>;
+export declare function resolveInitiativeViewReference(reference: string | undefined, options?: InitiativeSelectorOptions): Promise<InitiativeViewReference>;
+export interface InitiativeLinkReference {
+    store: string;
+    id: string;
+}
+export declare function resolveInitiativeLinkReference(reference: string | undefined, options?: InitiativeSelectorOptions): Promise<InitiativeLinkReference>;
+//# sourceMappingURL=resolution.d.ts.map