@fission-ai/openspec 1.4.1 → 1.6.0-beta.1

package/dist/core/archive.js

@@ -3,7 +3,59 @@ import path from 'path';
 import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
 import { Validator } from './validation/validator.js';
 import chalk from 'chalk';
+import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from './root-selection.js';
 import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, } from './specs-apply.js';
+function isMissingPathError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+async function listActiveChangeNames(changesDir) {
+    try {
+        const entries = await fs.readdir(changesDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive')
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (!isMissingPathError(error))
+            throw error;
+        return [];
+    }
+}
+/**
+ * JSON mode is non-interactive: any point where the human flow would prompt or
+ * print prose instead throws this error, which becomes a machine-readable
+ * status entry with a non-zero exit code.
+ */
+class ArchiveBlockedError extends Error {
+    diagnostic;
+    constructor(code, message, fix) {
+        super(message);
+        this.name = 'ArchiveBlockedError';
+        this.diagnostic = {
+            severity: 'error',
+            code,
+            message,
+            ...(fix ? { fix } : {}),
+        };
+    }
+}
+function toArchiveDiagnostic(error) {
+    if (error instanceof ArchiveBlockedError) {
+        return error.diagnostic;
+    }
+    if (isRootSelectionError(error)) {
+        return error.diagnostic;
+    }
+    return {
+        severity: 'error',
+        code: 'archive_error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
 /**
  * Recursively copy a directory. Used when fs.rename fails (e.g. EPERM on Windows).
  */
@@ -44,23 +96,63 @@ async function moveDirectory(src, dest) {
 }
 export class ArchiveCommand {
     async execute(changeName, options = {}) {
-        const targetPath = '.';
-        const changesDir = path.join(targetPath, 'openspec', 'changes');
-        const archiveDir = path.join(changesDir, 'archive');
-        const mainSpecsDir = path.join(targetPath, 'openspec', 'specs');
-        // Check if changes directory exists
+        const json = !!options.json;
+        let root;
         try {
-            await fs.access(changesDir);
+            root = await resolveOpenSpecRoot({
+                ...(options.store !== undefined ? { store: options.store } : {}),
+                ...(options.storePath !== undefined ? { storePath: options.storePath } : {}),
+            });
         }
-        catch {
-            throw new Error("No OpenSpec changes directory found. Run 'openspec init' first.");
+        catch (error) {
+            if (json && isRootSelectionError(error)) {
+                this.printJsonFailure(undefined, toArchiveDiagnostic(error));
+                return;
+            }
+            throw error;
         }
+        if (json) {
+            try {
+                const result = await this.run(changeName, options, root, true);
+                if (!result) {
+                    return;
+                }
+                console.log(JSON.stringify({ archive: result, root: toRootOutput(root) }, null, 2));
+            }
+            catch (error) {
+                this.printJsonFailure(root, toArchiveDiagnostic(error));
+            }
+            return;
+        }
+        emitStoreRootBanner(root);
+        await this.run(changeName, options, root, false);
+    }
+    printJsonFailure(root, diagnostic) {
+        console.log(JSON.stringify({
+            archive: null,
+            ...(root ? { root: toRootOutput(root) } : {}),
+            status: [diagnostic],
+        }, null, 2));
+        process.exitCode = 1;
+    }
+    /**
+     * Shared archive flow. In human mode (json=false) prompts and prose match
+     * the historical behavior and cancellations return null. In JSON mode no
+     * prose reaches stdout and every blocked path throws.
+     */
+    async run(changeName, options, root, json) {
+        const changesDir = root.changesDir;
+        const archiveDir = root.archiveDir;
+        const mainSpecsDir = root.specsDir;
         // Get change name interactively if not provided
         if (!changeName) {
+            if (json) {
+                throw new ArchiveBlockedError('archive_change_name_required', 'A change name is required: archive --json is non-interactive.', withStoreFlag(root, 'openspec archive <change-name> --json'));
+            }
             const selectedChange = await this.selectChange(changesDir);
             if (!selectedChange) {
                 console.log('No change selected. Aborting.');
-                return;
+                return null;
             }
             changeName = selectedChange;
         }
@@ -73,29 +165,34 @@ export class ArchiveCommand {
             }
         }
         catch {
-            throw new Error(`Change '${changeName}' not found.`);
+            const available = await listActiveChangeNames(changesDir);
+            throw new ArchiveBlockedError('archive_change_not_found', available.length > 0
+                ? `Change '${changeName}' not found. Available changes: ${available.join(', ')}`
+                : `Change '${changeName}' not found. No active changes exist in this root.`);
         }
         const skipValidation = options.validate === false || options.noValidate === true;
         // Validate specs and change before archiving
         if (!skipValidation) {
             const validator = new Validator();
             let hasValidationErrors = false;
-            // Validate proposal.md (non-blocking unless strict mode desired in future)
-            const changeFile = path.join(changeDir, 'proposal.md');
-            try {
-                await fs.access(changeFile);
-                const changeReport = await validator.validateChange(changeFile);
-                // Proposal validation is informative only (do not block archive)
-                if (!changeReport.valid) {
-                    console.log(chalk.yellow(`\nProposal warnings in proposal.md (non-blocking):`));
-                    for (const issue of changeReport.issues) {
-                        const symbol = issue.level === 'ERROR' ? '⚠' : (issue.level === 'WARNING' ? '⚠' : 'ℹ');
-                        console.log(chalk.yellow(`  ${symbol} ${issue.message}`));
+            // Validate proposal.md (informative only; human mode prints warnings)
+            if (!json) {
+                const changeFile = path.join(changeDir, 'proposal.md');
+                try {
+                    await fs.access(changeFile);
+                    const changeReport = await validator.validateChange(changeFile);
+                    // Proposal validation is informative only (do not block archive)
+                    if (!changeReport.valid) {
+                        console.log(chalk.yellow(`\nProposal warnings in proposal.md (non-blocking):`));
+                        for (const issue of changeReport.issues) {
+                            const symbol = issue.level === 'ERROR' ? '⚠' : (issue.level === 'WARNING' ? '⚠' : 'ℹ');
+                            console.log(chalk.yellow(`  ${symbol} ${issue.message}`));
+                        }
                     }
                 }
-            }
-            catch {
-                // Change file doesn't exist, skip validation
+                catch {
+                    // Change file doesn't exist, skip validation
+                }
             }
             // Validate delta-formatted spec files under the change directory if present
             const changeSpecsDir = path.join(changeDir, 'specs');
@@ -122,21 +219,32 @@ export class ArchiveCommand {
                 const deltaReport = await validator.validateChangeDeltaSpecs(changeDir);
                 if (!deltaReport.valid) {
                     hasValidationErrors = true;
-                    console.log(chalk.red(`\nValidation errors in change delta specs:`));
-                    for (const issue of deltaReport.issues) {
-                        if (issue.level === 'ERROR') {
-                            console.log(chalk.red(`  ✗ ${issue.message}`));
-                        }
-                        else if (issue.level === 'WARNING') {
-                            console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                    if (!json) {
+                        console.log(chalk.red(`\nValidation errors in change delta specs:`));
+                        for (const issue of deltaReport.issues) {
+                            if (issue.level === 'ERROR') {
+                                console.log(chalk.red(`  ✗ ${issue.message}`));
+                            }
+                            else if (issue.level === 'WARNING') {
+                                console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                            }
                         }
                     }
                 }
             }
             if (hasValidationErrors) {
+                if (json) {
+                    throw new ArchiveBlockedError('archive_validation_failed', `Validation failed for change '${changeName}'.`, `Run ${withStoreFlag(root, `openspec validate ${changeName}`)} for details, fix the errors, or rerun with --no-validate.`);
+                }
                 console.log(chalk.red('\nValidation failed. Please fix the errors before archiving.'));
                 console.log(chalk.yellow('To skip validation (not recommended), use --no-validate flag.'));
-                return;
+                process.exitCode = 1;
+                return null;
+            }
+        }
+        else if (json) {
+            if (!options.yes) {
+                throw new ArchiveBlockedError('archive_confirmation_required', 'Skipping validation requires confirmation: rerun with --yes.', withStoreFlag(root, 'openspec archive <change-name> --json --no-validate --yes'));
             }
         }
         else {
@@ -150,7 +258,7 @@ export class ArchiveCommand {
                 });
                 if (!proceed) {
                     console.log('Archive cancelled.');
-                    return;
+                    return null;
                 }
             }
             else {
@@ -160,12 +268,19 @@ export class ArchiveCommand {
             console.log(chalk.yellow(`Affected files: ${changeDir}`));
         }
         // Show progress and check for incomplete tasks
-        const progress = await getTaskProgressForChange(changesDir, changeName);
-        const status = formatTaskStatus(progress);
-        console.log(`Task status: ${status}`);
+        const progress = await getTaskProgressForChange(changesDir, changeName, path.resolve(changesDir, '..', '..'));
+        if (!json) {
+            const status = formatTaskStatus(progress);
+            console.log(`Task status: ${status}`);
+        }
         const incompleteTasks = Math.max(progress.total - progress.completed, 0);
         if (incompleteTasks > 0) {
-            if (!options.yes) {
+            if (json) {
+                if (!options.yes) {
+                    throw new ArchiveBlockedError('archive_tasks_incomplete', `${incompleteTasks} incomplete task(s) found for change '${changeName}'.`, 'Complete the tasks or rerun with --yes.');
+                }
+            }
+            else if (!options.yes) {
                 const { confirm } = await import('@inquirer/prompts');
                 const proceed = await confirm({
                     message: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
@@ -173,7 +288,7 @@ export class ArchiveCommand {
                 });
                 if (!proceed) {
                     console.log('Archive cancelled.');
-                    return;
+                    return null;
                 }
             }
             else {
@@ -181,21 +296,30 @@ export class ArchiveCommand {
             }
         }
         // Handle spec updates unless skipSpecs flag is set
+        let specsUpdated = false;
+        let totals;
         if (options.skipSpecs) {
-            console.log('Skipping spec updates (--skip-specs flag provided).');
+            if (!json) {
+                console.log('Skipping spec updates (--skip-specs flag provided).');
+            }
         }
         else {
             // Find specs to update
             const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
             if (specUpdates.length > 0) {
-                console.log('\nSpecs to update:');
-                for (const update of specUpdates) {
-                    const status = update.exists ? 'update' : 'create';
-                    const capability = path.basename(path.dirname(update.target));
-                    console.log(`  ${capability}: ${status}`);
+                if (!json) {
+                    console.log('\nSpecs to update:');
+                    for (const update of specUpdates) {
+                        const status = update.exists ? 'update' : 'create';
+                        const capability = path.basename(path.dirname(update.target));
+                        console.log(`  ${capability}: ${status}`);
+                    }
                 }
                 let shouldUpdateSpecs = true;
                 if (!options.yes) {
+                    if (json) {
+                        throw new ArchiveBlockedError('archive_confirmation_required', `Updating ${specUpdates.length} spec(s) requires confirmation: rerun with --yes.`, withStoreFlag(root, 'openspec archive <change-name> --json --yes'));
+                    }
                     const { confirm } = await import('@inquirer/prompts');
                     shouldUpdateSpecs = await confirm({
                         message: 'Proceed with spec updates?',
@@ -210,22 +334,29 @@ export class ArchiveCommand {
                     const prepared = [];
                     try {
                         for (const update of specUpdates) {
-                            const built = await buildUpdatedSpec(update, changeName);
+                            const built = await buildUpdatedSpec(update, changeName, { silent: json });
                             prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
                         }
                     }
                     catch (err) {
+                        if (json) {
+                            throw new ArchiveBlockedError('archive_spec_update_failed', String(err.message || err), 'Fix the change delta specs and rerun. No files were changed.');
+                        }
                         console.log(String(err.message || err));
                         console.log('Aborted. No files were changed.');
-                        return;
+                        process.exitCode = 1;
+                        return null;
                     }
-                    // All validations passed; pre-validate rebuilt full spec and then write files and display counts
-                    let totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
-                    for (const p of prepared) {
-                        const specName = path.basename(path.dirname(p.update.target));
-                        if (!skipValidation) {
+                    // Validate every rebuilt spec before writing any of them, so a
+                    // late validation failure really does leave all targets unchanged.
+                    if (!skipValidation) {
+                        for (const p of prepared) {
+                            const specName = path.basename(path.dirname(p.update.target));
                             const report = await new Validator().validateSpecContent(specName, p.rebuilt);
                             if (!report.valid) {
+                                if (json) {
+                                    throw new ArchiveBlockedError('archive_spec_validation_failed', `Rebuilt spec for '${specName}' failed validation. No files were changed.`, `Run ${withStoreFlag(root, `openspec validate ${specName}`)} after fixing the change deltas.`);
+                                }
                                 console.log(chalk.red(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`));
                                 for (const issue of report.issues) {
                                     if (issue.level === 'ERROR')
@@ -234,17 +365,30 @@ export class ArchiveCommand {
                                         console.log(chalk.yellow(`  ⚠ ${issue.message}`));
                                 }
                                 console.log('Aborted. No files were changed.');
-                                return;
+                                process.exitCode = 1;
+                                return null;
                             }
                         }
-                        await writeUpdatedSpec(p.update, p.rebuilt, p.counts);
-                        totals.added += p.counts.added;
-                        totals.modified += p.counts.modified;
-                        totals.removed += p.counts.removed;
-                        totals.renamed += p.counts.renamed;
                     }
-                    console.log(`Totals: + ${totals.added}, ~ ${totals.modified}, - ${totals.removed}, → ${totals.renamed}`);
-                    console.log('Specs updated successfully.');
+                    // All validations passed; write files and display counts
+                    const writeTotals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+                    for (const p of prepared) {
+                        await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
+                            silent: json,
+                            // Cross-root paths must be absolute when a store is selected.
+                            ...(isStoreSelectedRoot(root) ? { displayPath: p.update.target } : {}),
+                        });
+                        writeTotals.added += p.counts.added;
+                        writeTotals.modified += p.counts.modified;
+                        writeTotals.removed += p.counts.removed;
+                        writeTotals.renamed += p.counts.renamed;
+                    }
+                    specsUpdated = true;
+                    totals = writeTotals;
+                    if (!json) {
+                        console.log(`Totals: + ${writeTotals.added}, ~ ${writeTotals.modified}, - ${writeTotals.removed}, → ${writeTotals.renamed}`);
+                        console.log('Specs updated successfully.');
+                    }
                 }
             }
         }
@@ -252,29 +396,37 @@ export class ArchiveCommand {
         const archiveName = `${this.getArchiveDate()}-${changeName}`;
         const archivePath = path.join(archiveDir, archiveName);
         // Check if archive already exists
+        let archiveExists = false;
         try {
             await fs.access(archivePath);
-            throw new Error(`Archive '${archiveName}' already exists.`);
+            archiveExists = true;
         }
         catch (error) {
             if (error.code !== 'ENOENT') {
                 throw error;
             }
         }
+        if (archiveExists) {
+            throw new ArchiveBlockedError('archive_target_exists', `Archive '${archiveName}' already exists.`);
+        }
         // Create archive directory if needed
         await fs.mkdir(archiveDir, { recursive: true });
         // Move change to archive (uses copy+remove on EPERM/EXDEV, e.g. Windows)
         await moveDirectory(changeDir, archivePath);
-        console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+        if (!json) {
+            console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+        }
+        return {
+            change: changeName,
+            archivedAs: archiveName,
+            path: archivePath,
+            specsUpdated,
+            ...(totals ? { totals } : {}),
+        };
     }
     async selectChange(changesDir) {
         const { select } = await import('@inquirer/prompts');
-        // Get all directories in changes (excluding archive)
-        const entries = await fs.readdir(changesDir, { withFileTypes: true });
-        const changeDirs = entries
-            .filter(entry => entry.isDirectory() && entry.name !== 'archive')
-            .map(entry => entry.name)
-            .sort();
+        const changeDirs = await listActiveChangeNames(changesDir);
         if (changeDirs.length === 0) {
             console.log('No active changes found.');
             return null;
@@ -284,7 +436,7 @@ export class ArchiveCommand {
         try {
             const progressList = [];
             for (const id of changeDirs) {
-                const progress = await getTaskProgressForChange(changesDir, id);
+                const progress = await getTaskProgressForChange(changesDir, id, path.resolve(changesDir, '..', '..'));
                 const status = formatTaskStatus(progress);
                 progressList.push({ id, status });
             }

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

@@ -5,5 +5,5 @@ export { detectCompleted } from './state.js';
 export { artifactOutputExists, isGlobPattern, resolveArtifactOutputs } from './outputs.js';
 export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, type SchemaInfo, } from './resolver.js';
 export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, type ChangeContext, type LoadChangeContextOptions, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, type ArtifactPathSummary, } from './instruction-loader.js';
-export type { PlanningHomeSummary, AffectedAreasSummary, ActionContext, } from '../change-status-policy.js';
+export type { PlanningHomeSummary, ActionContext, } from '../change-status-policy.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -1,7 +1,9 @@
 import { ArtifactGraph } from './graph.js';
-import { type ActionContext, type AffectedAreasSummary, type PlanningHomeSummary } from '../change-status-policy.js';
+import { type ActionContext, type PlanningHomeSummary } from '../change-status-policy.js';
+import { type ProjectConfig } from '../project-config.js';
+import type { ReferenceIndexEntry } from '../references.js';
 import type { PlanningHome } from '../planning-home.js';
-import type { ChangeMetadata, InitiativeLink } from '../change-metadata/index.js';
+import type { ChangeMetadata } from '../change-metadata/index.js';
 import type { CompletedSet } from './types.js';
 /**
  * Error thrown when loading a template fails.
@@ -30,8 +32,6 @@ export interface ChangeContext {
     planningHome?: PlanningHome;
     /** Parsed change metadata, when present */
     metadata?: ChangeMetadata;
-    /** Stored initiative link, when this change is linked to shared context */
-    initiative?: InitiativeLink;
 }
 export interface LoadChangeContextOptions {
     changeDir?: string;
@@ -51,8 +51,6 @@ export interface ArtifactInstructions {
     changeDir: string;
     /** Resolved planning home for this change */
     planningHome?: PlanningHomeSummary;
-    /** Stored initiative link, when this change is linked to shared context */
-    initiative?: InitiativeLink;
     /** Output path pattern (e.g., "proposal.md") */
     outputPath: string;
     /** Absolute output path or glob pattern resolved under the change directory */
@@ -67,6 +65,8 @@ export interface ArtifactInstructions {
     context: string | undefined;
     /** Artifact-specific rules from config (constraints for AI, not to be included in output) */
     rules: string[] | undefined;
+    /** Referenced-store index (read-only upstream context; omitted when no references are declared) */
+    references?: ReferenceIndexEntry[];
     /** Template content (structure to follow - this IS the output format) */
     template: string;
     /** Dependencies with completion status and paths */
@@ -108,16 +108,13 @@ export interface ChangeStatus {
     changeName: string;
     /** Schema name */
     schemaName: string;
-    /** Resolved planning home for this change */
+    /** Planning home facts (generated skills derive the archive dir
+     * from planningHome.changesDir - a published agent contract). */
     planningHome?: PlanningHomeSummary;
-    /** Stored initiative link, when this change is linked to shared context */
-    initiative?: InitiativeLink;
     /** Full path to the change root */
     changeRoot: string;
     /** Absolute artifact path details keyed by artifact ID */
     artifactPaths: Record<string, ArtifactPathSummary>;
-    /** Workspace affected-area summary, when available */
-    affectedAreas?: AffectedAreasSummary;
     /** Plain-language next steps for users and agents */
     nextSteps: string[];
     /** Machine-readable action constraints for agents */
@@ -172,12 +169,20 @@ export declare function loadChangeContext(projectRoot: string, changeName: strin
  * @returns Enriched artifact instructions
  * @throws Error if artifact not found
  */
-export declare function generateInstructions(context: ChangeContext, artifactId: string, projectRoot?: string): ArtifactInstructions;
+export interface GenerateInstructionsOptions {
+    /** Pre-read project config; suppresses the internal read (no double read). */
+    projectConfig?: ProjectConfig | null;
+    /** Referenced-store index assembled at the command boundary. */
+    references?: ReferenceIndexEntry[];
+}
+export declare function generateInstructions(context: ChangeContext, artifactId: string, projectRoot?: string, options?: GenerateInstructionsOptions): ArtifactInstructions;
 /**
  * Formats the status of all artifacts in a change.
  *
  * @param context - Change context
  * @returns Formatted change status
  */
-export declare function formatChangeStatus(context: ChangeContext): ChangeStatus;
+export declare function formatChangeStatus(context: ChangeContext, options?: {
+    storeId?: string;
+}): ChangeStatus;
 //# sourceMappingURL=instruction-loader.d.ts.map

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

@@ -6,7 +6,7 @@ import { detectCompleted } from './state.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 { buildActionContext, buildNextSteps, 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();
@@ -79,24 +79,9 @@ export function loadChangeContext(projectRoot, changeName, schemaName, options =
         projectRoot,
         ...(options.planningHome ? { planningHome: options.planningHome } : {}),
         ...(metadata ? { metadata } : {}),
-        ...(metadata?.initiative ? { initiative: metadata.initiative } : {}),
     };
 }
-/**
- * Generates enriched instructions for creating an artifact.
- *
- * Instruction injection order:
- * 1. <context> - Project context from config (if present)
- * 2. <rules> - Artifact-specific rules from config (if present)
- * 3. <template> - Schema's template content
- *
- * @param context - Change context
- * @param artifactId - Artifact ID to generate instructions for
- * @param projectRoot - Project root directory (for reading config)
- * @returns Enriched artifact instructions
- * @throws Error if artifact not found
- */
-export function generateInstructions(context, artifactId, projectRoot) {
+export function generateInstructions(context, artifactId, projectRoot, options = {}) {
     const artifact = context.graph.getArtifact(artifactId);
     if (!artifact) {
         throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
@@ -106,9 +91,9 @@ export function generateInstructions(context, artifactId, projectRoot) {
     const unlocks = getUnlockedArtifacts(context.graph, artifactId);
     // Use projectRoot from context if not explicitly provided
     const effectiveProjectRoot = projectRoot ?? context.projectRoot;
-    // Try to read project config for context and rules
-    let projectConfig = null;
-    if (effectiveProjectRoot) {
+    // Use the pre-read config when provided; otherwise read it here.
+    let projectConfig = options.projectConfig ?? null;
+    if (options.projectConfig === undefined && effectiveProjectRoot) {
         try {
             projectConfig = readProjectConfig(effectiveProjectRoot);
         }
@@ -138,7 +123,6 @@ export function generateInstructions(context, artifactId, projectRoot) {
         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),
@@ -146,6 +130,7 @@ export function generateInstructions(context, artifactId, projectRoot) {
         instruction: artifact.instruction,
         context: configContext,
         rules: configRules,
+        ...(options.references !== undefined ? { references: options.references } : {}),
         template: templateContent,
         dependencies,
         unlocks,
@@ -183,7 +168,7 @@ function getUnlockedArtifacts(graph, artifactId) {
  * @param context - Change context
  * @returns Formatted change status
  */
-export function formatChangeStatus(context) {
+export function formatChangeStatus(context, options = {}) {
     // Load schema to get apply phase configuration
     const schema = resolveSchema(context.schemaName, context.projectRoot);
     const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
@@ -222,31 +207,23 @@ 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,
         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,
+            ...(options.storeId ? { storeId: options.storeId } : {}),
         }),
         actionContext: buildActionContext({
-            planningHome: context.planningHome,
             projectRoot: context.projectRoot,
             artifactIds,
         }),

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export { isKebabId } from '../id.js';
 export declare const InitiativeLinkSchema: z.ZodObject<{
     store: z.ZodString;
     id: z.ZodString;

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

@@ -1,6 +1,8 @@
 import { z } from 'zod';
+import { isKebabId } from '../id.js';
+export { isKebabId } from '../id.js';
 const KebabIdentifierSchema = (label) => z.string().superRefine((value, ctx) => {
-    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value)) {
+    if (!isKebabId(value)) {
         ctx.addIssue({
             code: 'custom',
             message: `${label} must be kebab-case with lowercase letters, numbers, and single hyphen separators`,
@@ -8,7 +10,7 @@ const KebabIdentifierSchema = (label) => z.string().superRefine((value, ctx) =>
     }
 });
 export const InitiativeLinkSchema = z.object({
-    store: KebabIdentifierSchema('Context store id'),
+    store: KebabIdentifierSchema('Store id'),
     id: KebabIdentifierSchema('Initiative id'),
 }).strict();
 // Per-change metadata schema. The schema field is validated against available