@fission-ai/openspec 1.11.0 → 1.13.0

package/README.md

@@ -172,6 +172,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
 → **[Customization](docs/customization.md)**: make it yours<br>
+→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec<br>
 → **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
 
@@ -223,21 +224,9 @@ openspec update
 
 ## Contributing
 
-**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+Open a discussion (for core design changes) or an issue before you open a PR, and link the issue or discussion from the PR. New features, significant refactors, and architectural changes need an OpenSpec change proposal first.
 
-**Larger changes** — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
-
-When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
-
-**AI-generated code is welcome** — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
-
-### Development
-
-- Install dependencies: `pnpm install`
-- Build: `pnpm run build`
-- Test: `pnpm test`
-- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
-- Conventional commits (one-line): `type(scope): subject`
+→ **[CONTRIBUTING.md](CONTRIBUTING.md)**: the full process, from first issue to merged PR
 
 ## Other
 

package/dist/cli/index.js

@@ -449,6 +449,7 @@ program
     .option('--changes', 'Validate all changes')
     .option('--specs', 'Validate all specs')
     .option('--archived', 'Validate that archived changes have all tasks completed (for pre-commit linting)')
+    .option('--report <full|findings>', 'Select bulk report content: full|findings; combine with --json for JSON')
     .option('--type <type>', 'Specify item type when ambiguous: change|spec')
     .option('--strict', 'Enable strict validation mode')
     .option('--json', 'Output validation results as JSON')

package/dist/commands/change.js

@@ -480,11 +480,12 @@ export class ChangeCommand {
             }
             else {
                 console.error(`Change "${changeName}" has issues`);
-                report.issues.forEach(issue => {
-                    const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
-                    const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
-                    console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
-                });
+            }
+            report.issues.forEach(issue => {
+                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                console.error(`${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+            });
+            if (!report.valid) {
                 // Next steps footer to guide fixing issues
                 this.printNextSteps(report.issues);
                 if (!options?.json) {

package/dist/commands/validate.d.ts

@@ -1,8 +1,11 @@
+import { toRootOutput } from '../core/root-selection.js';
+type ItemType = 'change' | 'spec';
 interface ExecuteOptions {
     all?: boolean;
     changes?: boolean;
     specs?: boolean;
     archived?: boolean;
+    report?: string;
     type?: string;
     strict?: boolean;
     json?: boolean;
@@ -12,6 +15,58 @@ interface ExecuteOptions {
     store?: string;
     storePath?: string;
 }
+interface BulkItemResult {
+    id: string;
+    type: ItemType;
+    valid: boolean;
+    issues: {
+        level: 'ERROR' | 'WARNING' | 'INFO';
+        path: string;
+        message: string;
+    }[];
+    durationMs: number;
+}
+type BulkScope = 'all' | 'changes' | 'specs' | 'archived';
+interface BulkValidationResult<T extends BulkItemResult = BulkItemResult> {
+    items: T[];
+    summary: {
+        totals: {
+            items: number;
+            passed: number;
+            failed: number;
+        };
+        byType: Partial<Record<ItemType, {
+            items: number;
+            passed: number;
+            failed: number;
+        }>>;
+    };
+    root: ReturnType<typeof toRootOutput>;
+}
+/** Findings are a distinct report, not a partial full-v1 items collection. */
+export declare function projectValidationFindings<T extends BulkItemResult>(full: BulkValidationResult<T>, scope: BulkScope): {
+    report: {
+        kind: "validation-findings";
+        version: "1.0";
+        scope: BulkScope;
+        returnedItems: number;
+        totalItems: number;
+    };
+    itemFindings: T[];
+    summary: {
+        totals: {
+            items: number;
+            passed: number;
+            failed: number;
+        };
+        byType: Partial<Record<ItemType, {
+            items: number;
+            passed: number;
+            failed: number;
+        }>>;
+    };
+    root: import("../core/root-selection.js").RootOutput;
+};
 export declare class ValidateCommand {
     execute(itemName: string | undefined, options?: ExecuteOptions): Promise<void>;
     private normalizeType;
@@ -29,6 +84,8 @@ export declare class ValidateCommand {
     private validateByType;
     private printReport;
     private printNextSteps;
+    private printFindingsReport;
+    private printBulkDetails;
     private runBulkValidation;
     /**
      * Lists archived change ids from the resolved root's archive directory,

package/dist/commands/validate.js

@@ -10,9 +10,54 @@ import { nearestMatches } from '../utils/match.js';
 import { promises as fs } from 'fs';
 import { getTaskProgressDetailForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+/** Findings are a distinct report, not a partial full-v1 items collection. */
+export function projectValidationFindings(full, scope) {
+    const itemFindings = full.items.filter(item => item.issues.length > 0);
+    return {
+        report: {
+            kind: 'validation-findings',
+            version: '1.0',
+            scope,
+            returnedItems: itemFindings.length,
+            totalItems: full.summary.totals.items,
+        },
+        itemFindings,
+        summary: full.summary,
+        root: full.root,
+    };
+}
 export class ValidateCommand {
     async execute(itemName, options = {}) {
         const bulk = options.all || options.changes || options.specs;
+        let findingsScope;
+        if (options.report !== undefined) {
+            const message = options.report !== 'full' && options.report !== 'findings'
+                ? `Unknown validation report '${options.report}'.`
+                : itemName !== undefined
+                    ? 'A validation report cannot be combined with an item name.'
+                    : options.archived && bulk
+                        ? 'A validation report cannot combine archived and active scopes.'
+                        : !options.archived && !bulk
+                            ? 'A validation report requires an explicit bulk scope.'
+                            : undefined;
+            if (message) {
+                const fix = 'Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes.';
+                if (options.json) {
+                    console.log(JSON.stringify({ status: [{ severity: 'error', code: 'invalid_validation_report_request', message, fix }] }, null, 2));
+                }
+                else {
+                    console.error(`Error: ${message}`);
+                    console.error(`Fix: ${fix}`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            if (options.report === 'findings') {
+                findingsScope = options.archived ? 'archived'
+                    : options.all || (options.changes && options.specs) ? 'all'
+                        : options.changes ? 'changes' : 'specs';
+            }
+        }
         const root = await resolveRootForCommand(options, {
             json: options.json,
             ...(bulk ? { allowImplicitRoot: false } : {}),
@@ -29,6 +74,7 @@ export class ValidateCommand {
             await this.runArchivedTaskValidation(root, {
                 json: !!options.json,
                 noInteractive: resolveNoInteractive(options),
+                findingsScope,
             });
             return;
         }
@@ -37,7 +83,7 @@ export class ValidateCommand {
             await this.runBulkValidation(root, {
                 changes: !!options.all || !!options.changes,
                 specs: !!options.all || !!options.specs,
-            }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
+            }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options), findingsScope });
             return;
         }
         // No item and no flags
@@ -191,11 +237,12 @@ export class ValidateCommand {
         }
         else {
             console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
-            for (const issue of report.issues) {
-                const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
-                const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
-                console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
-            }
+        }
+        for (const issue of report.issues) {
+            const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+            console.error(`${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+        }
+        if (!report.valid) {
             this.printNextSteps(type, id, root, report.issues);
         }
     }
@@ -228,6 +275,34 @@ export class ValidateCommand {
         console.error('Next steps:');
         bullets.forEach(b => console.error(`  ${b}`));
     }
+    printFindingsReport(full, scope, json, root) {
+        const findings = projectValidationFindings(full, scope);
+        if (json) {
+            console.log(JSON.stringify(findings, null, 2));
+            return;
+        }
+        console.log(`Scope: ${scope} (${findings.report.totalItems} items)`);
+        if (findings.itemFindings.length === 0) {
+            console.log('No item findings.');
+        }
+        for (const item of findings.itemFindings) {
+            console.error(`${item.type}/${item.id}`);
+            for (const issue of item.issues) {
+                console.error(`  [${issue.level}] ${issue.path}: ${issue.message}`);
+            }
+        }
+        const totals = findings.summary.totals;
+        console.log(`Totals: ${totals.passed} passed, ${totals.failed} failed (${totals.items} items)`);
+        if (scope !== 'archived')
+            this.printBulkDetails(full.items, root);
+    }
+    printBulkDetails(results, root) {
+        const firstFailure = results.find((res) => !res.valid);
+        if (firstFailure) {
+            const storeFlag = isStoreSelectedRoot(root) ? ` --store ${root.storeId}` : '';
+            console.log(`Details: openspec validate ${firstFailure.id} --type ${firstFailure.type}${storeFlag}`);
+        }
+    }
     async runBulkValidation(root, scope, opts) {
         const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
         const [changeIds, specIds] = await Promise.all([
@@ -269,7 +344,10 @@ export class ValidateCommand {
                     ...(scope.specs ? { spec: { items: 0, passed: 0, failed: 0 } } : {}),
                 },
             };
-            if (opts.json) {
+            if (opts.findingsScope) {
+                this.printFindingsReport({ items: [], summary, root: toRootOutput(root) }, opts.findingsScope, opts.json, root);
+            }
+            else if (opts.json) {
                 const out = { items: [], summary, version: '1.0', root: toRootOutput(root) };
                 console.log(JSON.stringify(out, null, 2));
             }
@@ -326,7 +404,10 @@ export class ValidateCommand {
                 ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
             },
         };
-        if (opts.json) {
+        if (opts.findingsScope) {
+            this.printFindingsReport({ items: results, summary, root: toRootOutput(root) }, opts.findingsScope, opts.json, root);
+        }
+        else if (opts.json) {
             const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
             console.log(JSON.stringify(out, null, 2));
         }
@@ -336,13 +417,13 @@ export class ValidateCommand {
                     console.log(`✓ ${res.type}/${res.id}`);
                 else
                     console.error(`✗ ${res.type}/${res.id}`);
+                for (const issue of res.issues) {
+                    const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                    console.error(`  ${prefix} [${issue.level}] ${issue.path}: ${issue.message}`);
+                }
             }
             console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
-            const firstFailure = results.find((res) => !res.valid);
-            if (firstFailure) {
-                const storeFlag = isStoreSelectedRoot(root) ? ` --store ${root.storeId}` : '';
-                console.log(`Details: openspec validate ${firstFailure.id} --type ${firstFailure.type}${storeFlag}`);
-            }
+            this.printBulkDetails(results, root);
         }
         process.exitCode = failed > 0 ? 1 : 0;
     }
@@ -438,6 +519,11 @@ export class ValidateCommand {
             totals: { items: results.length, passed, failed },
             byType: { change: summarizeType(results, 'change') },
         };
+        if (opts.findingsScope) {
+            this.printFindingsReport({ items: results, summary, root: toRootOutput(root) }, opts.findingsScope, opts.json, root);
+            process.exitCode = failed > 0 ? 1 : 0;
+            return;
+        }
         if (opts.json) {
             const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
             console.log(JSON.stringify(out, null, 2));

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, resolveArtifactOutputPath, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { isSpecsArtifactPath } from '../../core/artifact-graph/outputs.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
 import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
 import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedStoresSection, } from '../../core/references.js';
@@ -15,6 +16,7 @@ import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { loadOperationInputs, readProjectConfig, } from '../../core/project-config.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
 import { parseTaskLines } from '../../utils/task-progress.js';
+import { METADATA_FILENAME } from '../../utils/change-metadata.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
@@ -230,6 +232,99 @@ function toTaskItems(parsed) {
     }
     return tasks;
 }
+/**
+ * The command that builds one artifact.
+ *
+ * Every earlier remedy here named the `openspec-continue-change` skill, which
+ * the `core` profile never installs - the advice was a dead end for the default
+ * install. The CLI verb exists on every profile and is what the skill runs.
+ */
+function describeArtifactRemedy(changeName, artifactId, options = {}) {
+    const target = artifactId ?? '<artifact>';
+    const verb = options.many ? 'Create each with' : 'Create it with';
+    return (`${verb} \`openspec instructions ${target} --change ${changeName}\`` +
+        ` (\`openspec status --change ${changeName}\` shows what is left).`);
+}
+/**
+ * Finds the artifact a schema path is generated by, so a remedy can name it.
+ */
+function findArtifactIdFor(schema, generates) {
+    return schema.artifacts.find((artifact) => artifact.generates === generates)?.id;
+}
+/**
+ * Everything still to build before apply can run, in build order.
+ *
+ * Apply blocks on the schema's `apply.requires` alone, so its own list stops at
+ * the first hop: a change with only a proposal is told "Missing artifacts:
+ * tasks" while the specs `tasks` depends on are missing too. An agent that
+ * takes that literally writes the tracking file straight from the proposal and
+ * skips the artifacts in between - the failure reported in #834 and #869.
+ * Walking `requires` names the whole chain, the same set and order
+ * `openspec status` already prints, without changing what apply blocks on.
+ */
+function collectMissingPrerequisites(input) {
+    const { requiredArtifactIds, schema, buildOrder, completed } = input;
+    const byId = new Map(schema.artifacts.map((artifact) => [artifact.id, artifact]));
+    const missing = new Set();
+    const queue = [...requiredArtifactIds];
+    const seen = new Set(queue);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        const artifact = byId.get(id);
+        if (!artifact)
+            continue;
+        if (!completed.has(id))
+            missing.add(id);
+        for (const dependency of artifact.requires) {
+            if (seen.has(dependency))
+                continue;
+            seen.add(dependency);
+            queue.push(dependency);
+        }
+    }
+    const order = new Map(buildOrder.map((id, index) => [id, index]));
+    return [...missing].sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0));
+}
+/**
+ * Warnings apply reports alongside its instruction.
+ *
+ * Apply gates on the schema's `apply.requires` only, so a change whose tasks
+ * file was written ahead of its specs reads as ready even though no delta spec
+ * exists - the state `openspec validate` rejects. Blocking here would be a
+ * policy change; naming the gap is not, and it is what keeps apply from being
+ * the one surface that green-lights a change every other surface flags.
+ *
+ * Only reported once apply is past its own gate: for a change that has not
+ * reached tasks yet, the missing specs are the next step rather than a warning.
+ * Schemas that declare no spec-producing artifact carry `skip_specs` from
+ * creation, so this never fires on them.
+ */
+function collectApplyWarnings(input) {
+    const { state, schema, changeDir, changeName, skippedArtifacts } = input;
+    if (state === 'blocked')
+        return [];
+    const specArtifacts = schema.artifacts.filter((artifact) => isSpecsArtifactPath(artifact.generates));
+    if (specArtifacts.length === 0)
+        return [];
+    if (specArtifacts.some((artifact) => skippedArtifacts?.has(artifact.id)))
+        return [];
+    const hasDeltas = specArtifacts.some((artifact) => resolveArtifactOutputs(changeDir, artifact.generates).length > 0);
+    if (hasDeltas)
+        return [];
+    const metadataPath = path.join(changeDir, METADATA_FILENAME);
+    // The command names the artifact this schema actually declares, never the
+    // literal `specs`. A schema whose spec-producing artifact is `contracts` was
+    // told to run `openspec instructions specs`, an artifact it does not have,
+    // so the warning dead-ended at the exact step meant to resolve it. With more
+    // than one such artifact there is no single right answer, so the id becomes
+    // a placeholder rather than a guess.
+    const specTarget = specArtifacts.length === 1 ? specArtifacts[0].id : '<artifact-id>';
+    return [
+        `This change has no delta specs and does not declare \`skip_specs: true\`, so \`openspec validate ${changeName}\` fails on it. ` +
+            `Write the delta specs before implementing (\`openspec instructions ${specTarget} --change ${changeName}\`), ` +
+            `or add \`skip_specs: true\` to ${metadataPath} if this change really changes no specified behavior.`,
+    ];
+}
 /**
  * Generates apply instructions for implementing tasks from a change.
  * Schema-aware: reads apply phase configuration from schema to determine
@@ -267,6 +362,13 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             missingArtifacts.push(artifactId);
         }
     }
+    // Everything still to build, not just the first hop apply blocks on.
+    const missingPrerequisites = collectMissingPrerequisites({
+        requiredArtifactIds: [...requiredArtifactIds],
+        schema,
+        buildOrder: context.graph.getBuildOrder(),
+        completed: context.completed,
+    });
     // Build context files from all existing artifacts in schema
     const contextFiles = {};
     for (const artifact of schema.artifacts) {
@@ -297,20 +399,33 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     let instruction;
     if (missingArtifacts.length > 0) {
         state = 'blocked';
-        instruction = `Cannot apply this change yet. Missing artifacts: ${missingArtifacts.join(', ')}.\nUse the openspec-continue-change skill to create the missing artifacts first.`;
+        const chain = missingPrerequisites.length > missingArtifacts.length
+            ? `\nNot created yet, in build order: ${missingPrerequisites.join(', ')}.` +
+                ` Build the ones this change needs before applying - the schema says which are conditional.`
+            : '';
+        instruction =
+            `Cannot apply this change yet. Missing artifacts: ${missingArtifacts.join(', ')}.${chain}` +
+                `\n${describeArtifactRemedy(changeName, 
+                // Only name one when one is left: the first of several would be the
+                // schema's conditional artifact as often as not.
+                missingPrerequisites.length === 1 ? missingPrerequisites[0] : undefined, { many: missingPrerequisites.length > 1 })}`;
     }
     else if (tracksFile && !tracksFileExists) {
         // Tracking file configured but doesn't exist yet
         const tracksFilename = path.basename(tracksFile);
         state = 'blocked';
-        instruction = `The ${tracksFilename} file is missing and must be created.\nUse openspec-continue-change to generate the tracking file.`;
+        instruction =
+            `The ${tracksFilename} file is missing and must be created.` +
+                `\n${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
     else if (tracksFile && tracksFileExists && tasks.length === 0) {
         // Tracking file exists but lists nothing an agent can work on: either no
         // checkboxes at all, or only checkboxes with no text after them.
         const tracksFilename = path.basename(tracksFile);
         state = 'blocked';
-        instruction = `The ${tracksFilename} file exists but contains no tasks to work on.\nAdd tasks to ${tracksFilename} or regenerate it with openspec-continue-change.`;
+        instruction =
+            `The ${tracksFilename} file exists but contains no tasks to work on.` +
+                `\nAdd tasks to ${tracksFilename}, or rebuild it: ${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
     else if (tracksFile && remaining === 0 && total > 0) {
         state = 'all_done';
@@ -325,6 +440,13 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'ready';
         instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
     }
+    const warnings = collectApplyWarnings({
+        state,
+        schema,
+        changeDir,
+        changeName,
+        skippedArtifacts: context.skippedArtifacts,
+    });
     return {
         changeName,
         changeDir,
@@ -334,6 +456,8 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         tasks,
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
+        ...(missingPrerequisites.length > 0 ? { missingPrerequisites } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
         instruction,
         ...(references !== undefined ? { references } : {}),
         ...operationInputs,
@@ -375,7 +499,7 @@ export async function applyInstructionsCommand(options) {
     }
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, warnings, instruction } = instructions;
     console.log(`## Apply: ${changeName}`);
     console.log(`Schema: ${schemaName}`);
     console.log();
@@ -388,7 +512,18 @@ export function printApplyInstructionsText(instructions) {
         console.log('### ⚠️ Blocked');
         console.log();
         console.log(`Missing artifacts: ${missingArtifacts.join(', ')}`);
-        console.log('Use the openspec-continue-change skill to create these first.');
+        if (instructions.missingPrerequisites &&
+            instructions.missingPrerequisites.length > missingArtifacts.length) {
+            console.log(`Not created yet, in build order: ${instructions.missingPrerequisites.join(', ')}`);
+        }
+        console.log();
+    }
+    if (warnings && warnings.length > 0) {
+        console.log('### ⚠️ Warnings');
+        console.log();
+        for (const warning of warnings) {
+            console.log(`- ${warning}`);
+        }
         console.log();
     }
     // Context files (dynamically from schema)

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

@@ -30,6 +30,14 @@ export interface ApplyInstructions {
     tasks: TaskItem[];
     state: 'blocked' | 'all_done' | 'ready';
     missingArtifacts?: string[];
+    /**
+     * Everything still to build before apply can run, in build order - the
+     * transitive closure of the schema's `apply.requires`, so it can be longer
+     * than `missingArtifacts`, which stops at the first hop apply blocks on.
+     */
+    missingPrerequisites?: string[];
+    /** Non-blocking problems with the change, reported alongside the instruction. */
+    warnings?: string[];
     instruction: string;
     /** Referenced-store index (read-only upstream context; omitted when none declared) */
     references?: ReferenceIndexEntry[];

package/dist/core/command-generation/adapters/codeassistant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SourceCraft Code Assistant Command Adapter
+ *
+ * Formats commands for the SourceCraft Code Assistant VS Code extension.
+ *
+ * @see https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/slash-commands
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * SourceCraft Code Assistant adapter for command generation.
+ * File path: .codeassistant/commands/opsx-<id>.md
+ * Format: YAML frontmatter with description
+ */
+export declare const codeassistantAdapter: ToolCommandAdapter;
+//# sourceMappingURL=codeassistant.d.ts.map

package/dist/core/command-generation/adapters/codeassistant.js

@@ -0,0 +1,29 @@
+/**
+ * SourceCraft Code Assistant Command Adapter
+ *
+ * Formats commands for the SourceCraft Code Assistant VS Code extension.
+ *
+ * @see https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/slash-commands
+ */
+import path from 'path';
+import { escapeYamlValue } from '../yaml.js';
+/**
+ * SourceCraft Code Assistant adapter for command generation.
+ * File path: .codeassistant/commands/opsx-<id>.md
+ * Format: YAML frontmatter with description
+ */
+export const codeassistantAdapter = {
+    toolId: 'codeassistant',
+    getFilePath(commandId) {
+        return path.join('.codeassistant', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+description: ${escapeYamlValue(content.description)}
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=codeassistant.js.map

package/dist/core/command-generation/adapters/index.d.ts

@@ -26,6 +26,7 @@ export { kiroAdapter } from './kiro.js';
 export { ohMyPiAdapter } from './oh-my-pi.js';
 export { opencodeAdapter } from './opencode.js';
 export { piAdapter } from './pi.js';
+export { codeassistantAdapter } from './codeassistant.js';
 export { qoderAdapter } from './qoder.js';
 export { lingmaAdapter } from './lingma.js';
 export { qwenAdapter } from './qwen.js';

package/dist/core/command-generation/adapters/index.js

@@ -26,6 +26,7 @@ export { kiroAdapter } from './kiro.js';
 export { ohMyPiAdapter } from './oh-my-pi.js';
 export { opencodeAdapter } from './opencode.js';
 export { piAdapter } from './pi.js';
+export { codeassistantAdapter } from './codeassistant.js';
 export { qoderAdapter } from './qoder.js';
 export { lingmaAdapter } from './lingma.js';
 export { qwenAdapter } from './qwen.js';

package/dist/core/command-generation/registry.js

@@ -27,6 +27,7 @@ import { kiroAdapter } from './adapters/kiro.js';
 import { ohMyPiAdapter } from './adapters/oh-my-pi.js';
 import { opencodeAdapter } from './adapters/opencode.js';
 import { piAdapter } from './adapters/pi.js';
+import { codeassistantAdapter } from './adapters/codeassistant.js';
 import { qoderAdapter } from './adapters/qoder.js';
 import { lingmaAdapter } from './adapters/lingma.js';
 import { qwenAdapter } from './adapters/qwen.js';
@@ -63,6 +64,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(ohMyPiAdapter);
         CommandAdapterRegistry.register(opencodeAdapter);
         CommandAdapterRegistry.register(piAdapter);
+        CommandAdapterRegistry.register(codeassistantAdapter);
         CommandAdapterRegistry.register(qoderAdapter);
         CommandAdapterRegistry.register(lingmaAdapter);
         CommandAdapterRegistry.register(qwenAdapter);

package/dist/core/completions/command-registry.js

@@ -106,6 +106,12 @@ export const COMMAND_REGISTRY = [
                 name: 'archived',
                 description: 'Validate that archived changes have all tasks completed (for pre-commit linting)',
             },
+            {
+                name: 'report',
+                description: 'Select bulk report content',
+                takesValue: true,
+                values: ['full', 'findings'],
+            },
             COMMON_FLAGS.type,
             COMMON_FLAGS.strict,
             COMMON_FLAGS.jsonValidation,

package/dist/core/config.js

@@ -54,6 +54,7 @@ export const AI_TOOLS = [
     { name: 'Oh My Pi', value: 'oh-my-pi', available: true, successLabel: 'Oh My Pi', skillsDir: '.omp' },
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
     { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
+    { name: 'SourceCraft Code Assistant', value: 'codeassistant', available: true, successLabel: 'SourceCraft Code Assistant', skillsDir: '.codeassistant' },
     { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder', requiresIdeRestart: true },
     { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
     { name: 'Rovo Dev CLI', value: 'rovodev', available: true, successLabel: 'Rovo Dev CLI', skillsDir: '.rovodev', detectionPaths: ['.rovodev/skills', '.rovodev'] },