@fission-ai/openspec 1.3.0 → 1.4.0

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

@@ -3,7 +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();
@@ -32,10 +35,11 @@ export function loadTemplate(schemaName, templatePath, projectRoot) {
     if (!schemaDir) {
         throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
     }
-    const fullPath = path.join(schemaDir, 'templates', templatePath);
-    if (!fs.existsSync(fullPath)) {
-        throw new TemplateLoadError(`Template not found: ${fullPath}`, fullPath);
+    const templatePathOnDisk = path.join(schemaDir, 'templates', templatePath);
+    if (!fs.existsSync(templatePathOnDisk)) {
+        throw new TemplateLoadError(`Template not found: ${templatePathOnDisk}`, templatePathOnDisk);
     }
+    const fullPath = FileSystemUtils.canonicalizeExistingPath(templatePathOnDisk);
     try {
         return fs.readFileSync(fullPath, 'utf-8');
     }
@@ -57,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 = 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);
@@ -71,6 +77,9 @@ export function loadChangeContext(projectRoot, changeName, schemaName) {
         changeName,
         changeDir,
         projectRoot,
+        ...(options.planningHome ? { planningHome: options.planningHome } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(metadata?.initiative ? { initiative: metadata.initiative } : {}),
     };
 }
 /**
@@ -128,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,
@@ -177,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,
@@ -203,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/outputs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+export declare function isGlobPattern(pattern: string): boolean;
+/**
+ * Resolves an artifact's output path(s) to concrete files that currently exist.
+ * Returns absolute file paths. Glob matches are sorted for deterministic output.
+ */
+export declare function resolveArtifactOutputs(changeDir: string, generates: string): string[];
+/**
+ * Checks if an artifact has at least one resolved output file.
+ */
+export declare function artifactOutputExists(changeDir: string, generates: string): boolean;
+//# sourceMappingURL=outputs.d.ts.map

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

@@ -0,0 +1,39 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import { FileSystemUtils } from '../../utils/file-system.js';
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+export function isGlobPattern(pattern) {
+    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+}
+/**
+ * Resolves an artifact's output path(s) to concrete files that currently exist.
+ * Returns absolute file paths. Glob matches are sorted for deterministic output.
+ */
+export function resolveArtifactOutputs(changeDir, generates) {
+    if (!isGlobPattern(generates)) {
+        const fullPath = path.join(changeDir, generates);
+        try {
+            return fs.statSync(fullPath).isFile()
+                ? [FileSystemUtils.canonicalizeExistingPath(fullPath)]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    const normalizedPattern = FileSystemUtils.toPosixPath(generates);
+    const matches = fg
+        .sync(normalizedPattern, { cwd: changeDir, onlyFiles: true, absolute: true })
+        .map((match) => FileSystemUtils.canonicalizeExistingPath(path.normalize(match)));
+    return Array.from(new Set(matches)).sort();
+}
+/**
+ * Checks if an artifact has at least one resolved output file.
+ */
+export function artifactOutputExists(changeDir, generates) {
+    return resolveArtifactOutputs(changeDir, generates).length > 0;
+}
+//# sourceMappingURL=outputs.js.map

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

@@ -1,7 +1,5 @@
 import * as fs from 'node:fs';
-import * as path from 'node:path';
-import fg from 'fast-glob';
-import { FileSystemUtils } from '../../utils/file-system.js';
+import { artifactOutputExists } from './outputs.js';
 /**
  * Detects which artifacts are completed by checking file existence in the change directory.
  * Returns a Set of completed artifact IDs.
@@ -28,27 +26,6 @@ export function detectCompleted(graph, changeDir) {
  * Supports both simple paths and glob patterns.
  */
 function isArtifactComplete(generates, changeDir) {
-    const fullPattern = path.join(changeDir, generates);
-    // Check if it's a glob pattern
-    if (isGlobPattern(generates)) {
-        return hasGlobMatches(fullPattern);
-    }
-    // Simple file path - check if file exists
-    return fs.existsSync(fullPattern);
-}
-/**
- * Checks if a path contains glob pattern characters.
- */
-function isGlobPattern(pattern) {
-    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
-}
-/**
- * Checks if a glob pattern has any matches.
- * Normalizes Windows backslashes to forward slashes for cross-platform glob compatibility.
- */
-function hasGlobMatches(pattern) {
-    const normalizedPattern = FileSystemUtils.toPosixPath(pattern);
-    const matches = fg.sync(normalizedPattern, { onlyFiles: true });
-    return matches.length > 0;
+    return artifactOutputExists(changeDir, generates);
 }
 //# sourceMappingURL=state.js.map

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