@fission-ai/openspec 1.6.0 → 1.8.0

package/dist/commands/workflow/instructions.js

@@ -7,13 +7,14 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputPath, resolveArtifactOutputs, } from '../../core/artifact-graph/index.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';
 import { readRegistrySnapshot } from '../../core/store/registry.js';
-import { readProjectConfig } from '../../core/project-config.js';
+import { loadOperationInputs, readProjectConfig, } from '../../core/project-config.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
+import { parseTaskLines } from '../../utils/task-progress.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
@@ -55,10 +56,12 @@ export async function instructionsCommand(artifactId, options) {
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
+        const { projectConfig, references } = await loadRootConfigContext(root);
         // loadChangeContext will auto-detect schema from metadata if not provided
         const context = loadChangeContext(projectRoot, changeName, options.schema, {
             changeDir: getChangeDir(planningHome, changeName),
             planningHome,
+            projectConfig,
         });
         if (!artifactId) {
             spinner?.stop();
@@ -71,7 +74,6 @@ export async function instructionsCommand(artifactId, options) {
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
             throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
         }
-        const { projectConfig, references } = await loadRootConfigContext(root);
         const instructions = generateInstructions(context, artifactId, projectRoot, {
             projectConfig,
             references,
@@ -94,6 +96,17 @@ export function printInstructionsText(instructions, isBlocked) {
     // Opening tag
     console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
     console.log();
+    // Artifacts skipped via skip_specs get no creation directive: emitting the
+    // task/template anyway would prompt an agent to write spec files that
+    // validate then rejects as conflicting with the marker.
+    if (instructions.skipped) {
+        console.log('<warning>');
+        console.log(instructions.warning ?? 'This artifact is skipped (skip_specs is set in .openspec.yaml).');
+        console.log('</warning>');
+        console.log();
+        console.log('</artifact>');
+        return;
+    }
     // Warning for blocked artifacts
     if (isBlocked) {
         const missing = dependencies.filter((d) => !d.done).map((d) => d.id);
@@ -135,9 +148,18 @@ export function printInstructionsText(instructions, isBlocked) {
     // Dependencies (files to read for context)
     if (dependencies.length > 0) {
         console.log('<dependencies>');
-        console.log('Read these files for context before creating this artifact:');
+        console.log('Read the current contents of these files before creating this artifact (re-read them from disk even if you saw them earlier - they may have been edited):');
         console.log();
         for (const dep of dependencies) {
+            // A dependency satisfied via skip_specs has no files by design: telling
+            // the agent to read them (or calling them "done") would send it hunting
+            // for spec files that must not exist.
+            if (dep.skipped) {
+                console.log(`<dependency id="${dep.id}" status="skipped">`);
+                console.log(`  <description>Skipped: the change declares skip_specs, so this artifact has no files to read.</description>`);
+                console.log('</dependency>');
+                continue;
+            }
             const status = dep.done ? 'done' : 'missing';
             const fullPath = path.join(changeDir, dep.path);
             console.log(`<dependency id="${dep.id}" status="${status}">`);
@@ -185,25 +207,26 @@ export function printInstructionsText(instructions, isBlocked) {
 // Apply Instructions Command
 // -----------------------------------------------------------------------------
 /**
- * Parses tasks.md content and extracts task items with their completion status.
+ * Turns parsed task lines into the listed task items.
+ *
+ * A checkbox with no text after it is left out of the list: this is work for an
+ * agent to act on and tick off, and a bare `- [ ]` gives it nothing to match.
+ * It still counts toward progress, which is taken from every parsed line, so
+ * this list can be shorter than the totals beside it but never disagrees with
+ * `openspec list` or archive about how much work is left. An empty list is also
+ * what puts apply in its "nothing to work on" state, so a file of nothing but
+ * text-less checkboxes asks to be rewritten instead of being called done.
  */
-function parseTasksFile(content) {
+function toTaskItems(parsed) {
     const tasks = [];
-    const lines = content.split('\n');
-    let taskIndex = 0;
-    for (const line of lines) {
-        // Match checkbox patterns: - [ ] or - [x] or - [X]
-        const checkboxMatch = line.match(/^[-*]\s*\[([ xX])\]\s*(.+)\s*$/);
-        if (checkboxMatch) {
-            taskIndex++;
-            const done = checkboxMatch[1].toLowerCase() === 'x';
-            const description = checkboxMatch[2].trim();
-            tasks.push({
-                id: `${taskIndex}`,
-                description,
-                done,
-            });
-        }
+    for (const task of parsed) {
+        if (task.description.length === 0)
+            continue;
+        tasks.push({
+            id: `${tasks.length + 1}`,
+            description: task.description,
+            done: task.done,
+        });
     }
     return tasks;
 }
@@ -219,6 +242,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     const context = loadChangeContext(projectRoot, changeName, schemaName, {
         changeDir: getChangeDir(planningHome, changeName),
         planningHome,
+        projectConfig: options.projectConfig,
     });
     const changeDir = context.changeDir;
     // Get the full schema to access the apply phase configuration
@@ -229,9 +253,15 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
     const tracksFile = applyConfig?.tracks ?? null;
     const schemaInstruction = applyConfig?.instruction ?? null;
-    // Check which required artifacts are missing
+    const operationInputs = loadOperationInputs(options.projectConfig ?? null, 'apply');
+    // Check which required artifacts are missing. Artifacts the change skips
+    // via skip_specs count as present - their files must not exist, and
+    // status already reports them complete, so apply cannot block on them.
     const missingArtifacts = [];
     for (const artifactId of requiredArtifactIds) {
+        if (context.skippedArtifacts?.has(artifactId)) {
+            continue;
+        }
         const artifact = schema.artifacts.find((a) => a.id === artifactId);
         if (artifact && resolveArtifactOutputs(changeDir, artifact.generates).length === 0) {
             missingArtifacts.push(artifactId);
@@ -246,19 +276,21 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         }
     }
     // Parse tasks if tracking file exists
-    let tasks = [];
+    let parsedTasks = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = path.join(changeDir, tracksFile);
+        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
         tracksFileExists = fs.existsSync(tracksPath);
         if (tracksFileExists) {
             const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            tasks = parseTasksFile(tasksContent);
+            parsedTasks = parseTaskLines(tasksContent);
         }
     }
-    // Calculate progress
-    const total = tasks.length;
-    const complete = tasks.filter((t) => t.done).length;
+    const tasks = toTaskItems(parsedTasks);
+    // Calculate progress over every checkbox in the file, listed or not, so these
+    // numbers match `openspec list` and archive's incomplete-task check.
+    const total = parsedTasks.length;
+    const complete = parsedTasks.filter((task) => task.done).length;
     const remaining = total - complete;
     // Determine state and instruction
     let state;
@@ -273,11 +305,12 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'blocked';
         instruction = `The ${tracksFilename} file is missing and must be created.\nUse openspec-continue-change to generate the tracking file.`;
     }
-    else if (tracksFile && tracksFileExists && total === 0) {
-        // Tracking file exists but contains no tasks
+    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.\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 regenerate it with openspec-continue-change.`;
     }
     else if (tracksFile && remaining === 0 && total > 0) {
         state = 'all_done';
@@ -303,6 +336,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         instruction,
         ...(references !== undefined ? { references } : {}),
+        ...operationInputs,
     };
 }
 export async function applyInstructionsCommand(options) {
@@ -320,11 +354,13 @@ export async function applyInstructionsCommand(options) {
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
-        // generateApplyInstructions uses loadChangeContext which auto-detects schema
-        const { references } = await loadRootConfigContext(root);
+        // One parsed config snapshot supplies schema fallback, references, context,
+        // and operation guidance for this command.
+        const { projectConfig, references } = await loadRootConfigContext(root);
         const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
             planningHome,
             references,
+            projectConfig,
         });
         spinner?.stop();
         if (options.json) {
@@ -389,5 +425,57 @@ export function printApplyInstructionsText(instructions) {
     // Instruction
     console.log('### Instruction');
     console.log(instruction);
+    console.log();
+    printOperationInputsText(instructions);
+}
+export function generateArchiveInstructions(changeName, projectConfig) {
+    return {
+        changeName,
+        ...loadOperationInputs(projectConfig, 'archive'),
+    };
+}
+export async function archiveInstructionsCommand(options) {
+    const root = await resolveRootForCommand(options, { json: options.json });
+    if (!root) {
+        return;
+    }
+    const spinner = options.json ? undefined : ora('Loading archive inputs...').start();
+    try {
+        const changeName = await validateChangeExists(options.change, root.path, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
+        const projectConfig = readProjectConfig(root.path);
+        const instructions = generateArchiveInstructions(changeName, projectConfig);
+        spinner?.stop();
+        if (options.json) {
+            console.log(JSON.stringify({ ...instructions, root: toRootOutput(root) }, null, 2));
+            return;
+        }
+        printArchiveInstructionsText(instructions);
+    }
+    catch (error) {
+        spinner?.stop();
+        throw error;
+    }
+}
+export function printArchiveInstructionsText(instructions) {
+    console.log(`## Archive Inputs: ${instructions.changeName}`);
+    console.log();
+    printOperationInputsText(instructions);
+}
+function printOperationInputsText(inputs) {
+    if (inputs.context) {
+        console.log('### Project Context (required instruction input)');
+        console.log(inputs.context);
+        console.log();
+    }
+    if (inputs.operationGuidance && inputs.operationGuidance.length > 0) {
+        console.log('### Operation Guidance (advisory)');
+        for (const guidance of inputs.operationGuidance) {
+            console.log(`- ${guidance}`);
+        }
+        console.log();
+    }
+    if (!inputs.context && !inputs.operationGuidance) {
+        console.log('No project context or operation guidance configured.');
+    }
 }
 //# sourceMappingURL=instructions.js.map

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

@@ -33,6 +33,17 @@ export interface ApplyInstructions {
     instruction: string;
     /** Referenced-store index (read-only upstream context; omitted when none declared) */
     references?: ReferenceIndexEntry[];
+    /** Current project background from the selected root. */
+    context?: string;
+    /** Current advisory guidance for apply. */
+    operationGuidance?: string[];
+}
+export interface ArchiveInstructions {
+    changeName: string;
+    /** Current project background from the selected root. */
+    context?: string;
+    /** Current advisory guidance for archive. */
+    operationGuidance?: string[];
 }
 export declare const DEFAULT_SCHEMA = "spec-driven";
 export declare function printJson(payload: unknown): void;
@@ -44,11 +55,11 @@ export declare function isColorDisabled(): boolean;
 /**
  * Gets the color function based on status.
  */
-export declare function getStatusColor(status: 'done' | 'ready' | 'blocked'): (text: string) => string;
+export declare function getStatusColor(status: 'done' | 'skipped' | 'ready' | 'blocked'): (text: string) => string;
 /**
  * Gets the status indicator for an artifact.
  */
-export declare function getStatusIndicator(status: 'done' | 'ready' | 'blocked'): string;
+export declare function getStatusIndicator(status: 'done' | 'skipped' | 'ready' | 'blocked'): string;
 /**
  * Returns the list of available change directory names under openspec/changes/.
  * Excludes the archive directory and hidden directories.

package/dist/commands/workflow/shared.js

@@ -9,7 +9,6 @@ import path from 'path';
 import * as fs from 'fs';
 import { getSchemaDir, listSchemas } from '../../core/artifact-graph/index.js';
 import { isRootSelectionError } from '../../core/root-selection.js';
-import { validateChangeName } from '../../utils/change-utils.js';
 // -----------------------------------------------------------------------------
 // Constants
 // -----------------------------------------------------------------------------
@@ -46,6 +45,8 @@ export function getStatusColor(status) {
     switch (status) {
         case 'done':
             return chalk.green;
+        case 'skipped':
+            return chalk.gray;
         case 'ready':
             return chalk.yellow;
         case 'blocked':
@@ -60,6 +61,8 @@ export function getStatusIndicator(status) {
     switch (status) {
         case 'done':
             return color('[x]');
+        case 'skipped':
+            return color('[~]');
         case 'ready':
             return color('[ ]');
         case 'blocked':
@@ -84,6 +87,33 @@ export async function getAvailableChanges(projectRoot, changesDir = path.join(pr
         throw error;
     }
 }
+/**
+ * Validates a change name used to look up an existing change directory.
+ * Lookup accepts any directory name that `getAvailableChanges` could return
+ * (the kebab-case convention in `validateChangeName` applies at creation
+ * time only); it only rejects names that would escape the changes directory
+ * or address entries `getAvailableChanges` excludes (hidden dirs, archive).
+ *
+ * @returns An error message, or undefined if the name is safe to look up
+ */
+function validateChangeLookupName(changeName) {
+    if (changeName === '.' || changeName === '..') {
+        return 'Change name cannot be a relative path segment';
+    }
+    if (changeName.includes('/') || changeName.includes('\\')) {
+        return 'Change name cannot contain path separators';
+    }
+    if (changeName.includes('\0')) {
+        return 'Change name cannot contain null characters';
+    }
+    if (changeName.startsWith('.')) {
+        return 'Change name cannot start with a dot';
+    }
+    if (changeName === 'archive') {
+        return "'archive' is reserved for archived changes";
+    }
+    return undefined;
+}
 /**
  * Validates that a change exists and returns available changes if not.
  * Checks directory existence directly to support scaffolded changes (without proposal.md).
@@ -100,9 +130,9 @@ export async function validateChangeExists(changeName, projectRoot, changesDir =
         throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
     }
     // Validate change name format to prevent path traversal
-    const nameValidation = validateChangeName(changeName);
-    if (!nameValidation.valid) {
-        throw new Error(`Invalid change name '${changeName}': ${nameValidation.error}`);
+    const lookupError = validateChangeLookupName(changeName);
+    if (lookupError) {
+        throw new Error(`Invalid change name '${changeName}': ${lookupError}`);
     }
     // Check directory existence directly
     const changePath = path.join(changesDir, changeName);

package/dist/commands/workflow/status.js

@@ -67,26 +67,31 @@ export async function statusCommand(options) {
 }
 export function printStatusText(status) {
     const doneCount = status.artifacts.filter((a) => a.status === 'done').length;
-    const total = status.artifacts.length;
+    const skippedCount = status.artifacts.filter((a) => a.status === 'skipped').length;
+    const total = status.artifacts.length - skippedCount;
     console.log(`Change: ${status.changeName}`);
     console.log(`Schema: ${status.schemaName}`);
     if (status.changeRoot) {
         console.log(`Change root: ${status.changeRoot}`);
     }
-    console.log(`Progress: ${doneCount}/${total} artifacts complete`);
+    const skippedSuffix = skippedCount > 0 ? ` (${skippedCount} skipped)` : '';
+    console.log(`Progress: ${doneCount}/${total} artifacts complete${skippedSuffix}`);
     console.log();
     for (const artifact of status.artifacts) {
         const indicator = getStatusIndicator(artifact.status);
         const color = getStatusColor(artifact.status);
         let line = `${indicator} ${artifact.id}`;
+        if (artifact.status === 'skipped') {
+            line += color(' (skipped: change declares skip_specs)');
+        }
         if (artifact.status === 'blocked' && artifact.missingDeps && artifact.missingDeps.length > 0) {
             line += color(` (blocked by: ${artifact.missingDeps.join(', ')})`);
         }
         console.log(line);
     }
-    if (status.isComplete) {
+    if (status.isPlanningComplete) {
         console.log();
-        console.log(chalk.green('All artifacts complete!'));
+        console.log(chalk.green('All planning artifacts complete!'));
     }
 }
 //# sourceMappingURL=status.js.map

package/dist/commands/workflow/templates.js

@@ -39,11 +39,21 @@ export async function templatesCommand(options) {
         else {
             source = 'package';
         }
-        const templates = graph.getAllArtifacts().map((artifact) => ({
-            artifactId: artifact.id,
-            templatePath: FileSystemUtils.canonicalizeExistingPath(path.join(schemaDir, 'templates', artifact.template)),
-            source,
-        }));
+        const templatesDir = path.join(schemaDir, 'templates');
+        const templates = graph.getAllArtifacts().map((artifact) => {
+            const templatePath = path.join(templatesDir, artifact.template);
+            try {
+                FileSystemUtils.assertPathWithin(templatesDir, templatePath);
+                return {
+                    artifactId: artifact.id,
+                    templatePath: FileSystemUtils.canonicalizeExistingPath(templatePath),
+                    source,
+                };
+            }
+            catch {
+                throw new Error(`Template '${artifact.template}' for artifact '${artifact.id}' points outside the schema templates directory`);
+            }
+        });
         spinner?.stop();
         if (options.json) {
             const output = {};

package/dist/core/archive.d.ts

@@ -1,3 +1,17 @@
+/**
+ * True when the ONLY thing wrong with a rebuilt spec is that it has no
+ * requirements. That is the exact failure retiring a capability replaces
+ * (#1302); anything else means the spec is broken in a way the author still has
+ * to fix, so archive must abort exactly as it always did instead of retiring.
+ *
+ * Asking the validator - rather than counting requirement blocks a second time -
+ * is what makes "this spec could not have been written anyway" true by
+ * construction. The two counts genuinely disagree: `MarkdownParser` accepts any
+ * `###` heading under `## Requirements` as a requirement, while the delta block
+ * parser only indexes canonical `### Requirement:` headers and sweeps the rest
+ * into the preamble, which survives into the rebuilt spec.
+ */
+export declare function isRetirableSpec(specName: string, rebuilt: string): Promise<boolean>;
 export interface ArchiveOptions {
     yes?: boolean;
     skipSpecs?: boolean;
@@ -17,6 +31,5 @@ export declare class ArchiveCommand {
      */
     private run;
     private selectChange;
-    private getArchiveDate;
 }
 //# sourceMappingURL=archive.d.ts.map