@fission-ai/openspec 1.13.0 → 1.13.2

package/dist/commands/workflow/instructions.js

@@ -7,11 +7,12 @@
 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 { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { isSpecsArtifactPath } from '../../core/artifact-graph/outputs.js';
+import { findUnreadDeltaFiles } from '../../utils/spec-discovery.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 { assembleReferenceIndex, escapeEnvelopeAttribute, escapeEnvelopeTags, renderReferencedStoresBlock, renderReferencedStoresSection, sanitizeInline, } from '../../core/references.js';
 import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { loadOperationInputs, readProjectConfig, } from '../../core/project-config.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
@@ -95,8 +96,12 @@ export async function instructionsCommand(artifactId, options) {
 }
 export function printInstructionsText(instructions, isBlocked) {
     const { artifactId, changeName, schemaName, changeDir, resolvedOutputPath, description, instruction, context, rules, template, dependencies, unlocks, } = instructions;
-    // Opening tag
-    console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
+    // Opening tag. The change name is a directory name read from disk, and the
+    // read path rejects only separators and NUL - a quote in it would otherwise
+    // close the attribute and forge siblings on this tag.
+    console.log(`<artifact id="${escapeEnvelopeAttribute(artifactId)}"` +
+        ` change="${escapeEnvelopeAttribute(changeName)}"` +
+        ` schema="${escapeEnvelopeAttribute(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
@@ -120,15 +125,15 @@ export function printInstructionsText(instructions, isBlocked) {
     }
     // Task directive
     console.log('<task>');
-    console.log(`Create the ${artifactId} artifact for change "${changeName}".`);
-    console.log(description);
+    console.log(`Create the ${escapeEnvelopeTags(artifactId)} artifact for change "${escapeEnvelopeTags(changeName)}".`);
+    console.log(escapeEnvelopeTags(description));
     console.log('</task>');
     console.log();
     // Project context (AI constraint - do not include in output)
     if (context) {
         console.log('<project_context>');
         console.log('<!-- This is background information for you. Do NOT include this in your output. -->');
-        console.log(context);
+        console.log(escapeEnvelopeTags(context));
         console.log('</project_context>');
         console.log();
     }
@@ -142,7 +147,9 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log('<rules>');
         console.log('<!-- These are constraints for you to follow. Do NOT include this in your output. -->');
         for (const rule of rules) {
-            console.log(`- ${rule}`);
+            // Flattened so a newline cannot forge a sibling bullet, but never
+            // truncated: these are instructions an agent has to follow in full.
+            console.log(`- ${escapeEnvelopeTags(sanitizeInline(rule, Infinity))}`);
         }
         console.log('</rules>');
         console.log();
@@ -166,7 +173,7 @@ export function printInstructionsText(instructions, isBlocked) {
             const fullPath = path.join(changeDir, dep.path);
             console.log(`<dependency id="${dep.id}" status="${status}">`);
             console.log(`  <path>${fullPath}</path>`);
-            console.log(`  <description>${dep.description}</description>`);
+            console.log(`  <description>${escapeEnvelopeTags(dep.description)}</description>`);
             console.log('</dependency>');
         }
         console.log('</dependencies>');
@@ -180,14 +187,17 @@ export function printInstructionsText(instructions, isBlocked) {
     // Instruction (guidance)
     if (instruction) {
         console.log('<instruction>');
-        console.log(instruction.trim());
+        console.log(escapeEnvelopeTags(instruction.trim()));
         console.log('</instruction>');
         console.log();
     }
     // Template
     console.log('<template>');
     console.log('<!-- Use this as the structure for your output file. Fill in the sections. -->');
-    console.log(template.trim());
+    // Copied verbatim into the artifact file, so its `<!-- ... -->` comments and
+    // `<placeholder>` markers must survive - only the envelope's own closing
+    // tags are neutralized.
+    console.log(escapeEnvelopeTags(template.trim()));
     console.log('</template>');
     console.log();
     // Success criteria placeholder
@@ -298,8 +308,12 @@ function collectMissingPrerequisites(input) {
  * 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.
+ *
+ * A delta file the merge path never reads (specs/<capability>.md, a note
+ * beside spec.md) still satisfies the specs glob, so it reads as written here
+ * while validate rejects it and archive would drop it. Each one is named.
  */
-function collectApplyWarnings(input) {
+async function collectApplyWarnings(input) {
     const { state, schema, changeDir, changeName, skippedArtifacts } = input;
     if (state === 'blocked')
         return [];
@@ -308,9 +322,11 @@ function collectApplyWarnings(input) {
         return [];
     if (specArtifacts.some((artifact) => skippedArtifacts?.has(artifact.id)))
         return [];
+    const warnings = (await findUnreadDeltaFiles(path.join(changeDir, 'specs'))).map((file) => `specs/${file.path} is not a capability's spec.md, so \`openspec validate ${changeName}\` rejects it and archive never merges it. ` +
+        `Move its requirements into specs/${file.expected}.`);
     const hasDeltas = specArtifacts.some((artifact) => resolveArtifactOutputs(changeDir, artifact.generates).length > 0);
     if (hasDeltas)
-        return [];
+        return warnings;
     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
@@ -320,6 +336,7 @@ function collectApplyWarnings(input) {
     // a placeholder rather than a guess.
     const specTarget = specArtifacts.length === 1 ? specArtifacts[0].id : '<artifact-id>';
     return [
+        ...warnings,
         `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.`,
@@ -377,15 +394,28 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             contextFiles[artifact.id] = outputs;
         }
     }
-    // Parse tasks if tracking file exists
+    // Parse every concrete file matched by apply.tracks. A tracking path may be
+    // a glob owned by an artifact with any ID, so treating it as one literal
+    // path loses task evidence for valid custom schemas.
     let parsedTasks = [];
+    const unavailableTrackingFiles = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
-        tracksFileExists = fs.existsSync(tracksPath);
-        if (tracksFileExists) {
-            const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            parsedTasks = parseTaskLines(tasksContent);
+        const tracksPaths = resolveArtifactOutputs(changeDir, tracksFile);
+        tracksFileExists = tracksPaths.length > 0;
+        for (const tracksPath of tracksPaths) {
+            try {
+                const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
+                parsedTasks.push(...parseTaskLines(tasksContent));
+            }
+            catch (error) {
+                const code = error?.code;
+                const message = error instanceof Error ? error.message : String(error);
+                unavailableTrackingFiles.push({
+                    path: tracksPath,
+                    reason: code && !message.includes(code) ? `${code}: ${message}` : message,
+                });
+            }
         }
     }
     const tasks = toTaskItems(parsedTasks);
@@ -418,6 +448,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             `The ${tracksFilename} file is missing and must be created.` +
                 `\n${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
+    else if (tracksFile && unavailableTrackingFiles.length > 0 && tasks.length === 0) {
+        state = 'blocked';
+        instruction = 'No readable task descriptions are available.';
+    }
     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.
@@ -427,7 +461,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             `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) {
+    else if (tracksFile &&
+        unavailableTrackingFiles.length === 0 &&
+        remaining === 0 &&
+        total > 0) {
         state = 'all_done';
         instruction = 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
     }
@@ -440,7 +477,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({
+    if (unavailableTrackingFiles.length > 0) {
+        const unavailableDetails = unavailableTrackingFiles
+            .map((file) => `- ${file.path}: ${file.reason}`)
+            .join('\n');
+        instruction += `\nTask completion is not verified because tracking evidence was unavailable:\n${unavailableDetails}`;
+    }
+    const warnings = await collectApplyWarnings({
         state,
         schema,
         changeDir,
@@ -454,6 +497,8 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
+        taskTrackingConfigured: tracksFile !== null,
+        ...(unavailableTrackingFiles.length > 0 ? { unavailableTrackingFiles } : {}),
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         ...(missingPrerequisites.length > 0 ? { missingPrerequisites } : {}),
@@ -599,13 +644,15 @@ export function printArchiveInstructionsText(instructions) {
 function printOperationInputsText(inputs) {
     if (inputs.context) {
         console.log('### Project Context (required instruction input)');
+        // Printed verbatim on purpose. Escaping a leading `#` would also fire inside
+        // fenced code (`# install deps`), so heading forgery is not guarded here.
         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(`- ${sanitizeInline(guidance, Infinity)}`);
         }
         console.log();
     }

package/dist/commands/workflow/new-change.js

@@ -6,6 +6,7 @@
  * root; initiative linking and workspace affected areas are no longer part of
  * this command.
  */
+import chalk from 'chalk';
 import ora from 'ora';
 import path from 'path';
 import { createChange, validateChangeName } from '../../utils/change-utils.js';
@@ -33,6 +34,24 @@ function printCreatedChangeHuman(payload, root) {
     console.log(`Schema: ${payload.change.schema}`);
     console.log(`Next: ${withStoreFlag(root, `openspec status --change ${payload.change.id}`)}`);
 }
+/**
+ * An implicit root is the fallback taken when no `openspec/` directory was
+ * found: creating a change there materializes OpenSpec in whatever directory
+ * the caller happened to be in, which is how an agent ends up adopting a
+ * project that never ran `openspec init` (#1645). The creation itself stays
+ * zero-config; this only makes it visible.
+ */
+function printImplicitRootNotice(root) {
+    if (root.source !== 'implicit') {
+        return;
+    }
+    const openspecDir = path.dirname(root.changesDir);
+    const relative = path.relative(process.cwd(), openspecDir);
+    const location = relative && !relative.startsWith('..') ? relative : openspecDir;
+    console.log();
+    console.log(chalk.dim(`Note: no OpenSpec root was found here, so one was created at ${location}/.`));
+    console.log(chalk.dim('Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.'));
+}
 export async function newChangeCommand(name, options) {
     const spinner = options.json ? undefined : ora();
     try {
@@ -89,6 +108,7 @@ export async function newChangeCommand(name, options) {
         }
         spinner?.stop();
         printCreatedChangeHuman(payload, root);
+        printImplicitRootNotice(root);
     }
     catch (error) {
         spinner?.stop();

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

@@ -28,6 +28,11 @@ export interface ApplyInstructions {
         remaining: number;
     };
     tasks: TaskItem[];
+    taskTrackingConfigured: boolean;
+    unavailableTrackingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
     state: 'blocked' | 'all_done' | 'ready';
     missingArtifacts?: string[];
     /**

package/dist/commands/workflow/shared.js

@@ -6,6 +6,7 @@
  */
 import chalk from 'chalk';
 import path from 'path';
+import { describeNestedChange, findNestedChangesIn, } from '../../utils/nested-change.js';
 import * as fs from 'fs';
 import { getSchemaDir, listSchemas } from '../../core/artifact-graph/index.js';
 import { isRootSelectionError } from '../../core/root-selection.js';
@@ -144,6 +145,13 @@ export async function validateChangeExists(changeName, projectRoot, changesDir =
         }
         throw new Error(`Change '${changeName}' not found. Available changes:\n  ${available.join('\n  ')}`);
     }
+    // The directory exists but is a namespace folder wrapping nested change
+    // directories. Every artifact lookup below it would report "not started" for
+    // work that is in fact there, so say what is actually wrong instead (#1846).
+    const nested = await findNestedChangesIn(changesDir, changeName);
+    if (nested) {
+        throw new Error(describeNestedChange(nested));
+    }
     return changeName;
 }
 /**

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

@@ -14,5 +14,9 @@ export interface StatusOptions {
 }
 export declare const BATCH_STATUS_FAILURE_PAYLOAD: Record<string, unknown>;
 export declare function statusCommand(options: StatusOptions): Promise<void>;
-export declare function printStatusText(status: ChangeStatus): void;
+export interface PrintStatusTextOptions {
+    /** Selected store id, so the printed command carries `--store`. */
+    storeId?: string;
+}
+export declare function printStatusText(status: ChangeStatus, options?: PrintStatusTextOptions): void;
 //# sourceMappingURL=status.d.ts.map

package/dist/commands/workflow/status.js

@@ -8,7 +8,9 @@ import chalk from 'chalk';
 import { getChangeDir } from '../../core/planning-home.js';
 import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
 import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
+import { resolveNextStep } from '../../core/change-status-policy.js';
 import { asStatus } from '../shared-output.js';
+import { describeNestedChange, findNestedChanges, } from '../../utils/nested-change.js';
 import { validateChangeExists, validateSchemaExists, getAvailableChanges, getStatusIndicator, getStatusColor, } from './shared.js';
 // The --all --json failure null-shape. Root-selection failures (handled in
 // resolveRootForCommand) and thrown errors (caught by the CLI wrapper) must
@@ -37,12 +39,16 @@ export async function statusCommand(options) {
         const projectRoot = root.path;
         const rootOutput = toRootOutput(root);
         const newChangeHint = withStoreFlag(root, 'openspec new change <name>');
+        // One store-flag decision serves the JSON `nextSteps` sentence and the text
+        // `Next:` line, so a store-selected root can never carry `--store` in one
+        // and drop it from the other.
+        const storeOptions = isStoreSelectedRoot(root) ? { storeId: root.storeId } : {};
         // Single definition of "load one change's status" so the batch and
         // single-change payloads can never drift apart.
         const loadStatus = (changeName) => formatChangeStatus(loadChangeContext(projectRoot, changeName, options.schema, {
             changeDir: getChangeDir(planningHome, changeName),
             planningHome,
-        }), isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
+        }), storeOptions);
         // Handle no-changes case gracefully — status is informational,
         // so "no changes" is a valid state, not an error.
         if (!options.change) {
@@ -66,7 +72,23 @@ export async function statusCommand(options) {
                 // with the same comparator validate --all uses so the two batch
                 // commands order a given change set identically.
                 const entries = [];
+                // The sweep reads each directory straight through `loadStatus`, so a
+                // namespace folder wrapping nested changes would report a whole
+                // artifact plan for work that is not there (#1846). It carries the same
+                // per-change diagnostic a malformed change does.
+                const nestedByName = new Map((await findNestedChanges(root.changesDir, available)).map((finding) => [
+                    finding.name,
+                    finding,
+                ]));
                 for (const changeName of available.sort((a, b) => a.localeCompare(b))) {
+                    const nested = nestedByName.get(changeName);
+                    if (nested) {
+                        entries.push({
+                            changeName,
+                            status: [asStatus(new Error(describeNestedChange(nested)), 'change_error')],
+                        });
+                        continue;
+                    }
                     try {
                         entries.push(loadStatus(changeName));
                     }
@@ -90,7 +112,7 @@ export async function statusCommand(options) {
                         console.log();
                     }
                     if ('artifacts' in entry) {
-                        printStatusText(entry);
+                        printStatusText(entry, storeOptions);
                     }
                     else {
                         console.log(chalk.red(`✗ ${entry.changeName}: ${entry.status[0]?.message}`));
@@ -122,14 +144,14 @@ export async function statusCommand(options) {
             console.log(JSON.stringify({ ...status, root: rootOutput }, null, 2));
             return;
         }
-        printStatusText(status);
+        printStatusText(status, storeOptions);
     }
     catch (error) {
         spinner?.stop();
         throw error;
     }
 }
-export function printStatusText(status) {
+export function printStatusText(status, options = {}) {
     const doneCount = status.artifacts.filter((a) => a.status === 'done').length;
     const skippedCount = status.artifacts.filter((a) => a.status === 'skipped').length;
     const total = status.artifacts.length - skippedCount;
@@ -153,9 +175,24 @@ export function printStatusText(status) {
         }
         console.log(line);
     }
-    if (status.isPlanningComplete) {
+    // Derived from the same inputs as the JSON `nextSteps` sentence, so the two
+    // surfaces always name the same command. Without this line the text surface
+    // reports state and no verb, which leaves someone resuming a change - after a
+    // lost session, or on a change they did not start - with nowhere to go.
+    const nextStep = resolveNextStep({
+        changeName: status.changeName,
+        artifactStatuses: status.artifacts,
+        allArtifactsComplete: status.isPlanningComplete,
+        ...(options.storeId ? { storeId: options.storeId } : {}),
+    });
+    if (status.isPlanningComplete || nextStep) {
         console.log();
+    }
+    if (status.isPlanningComplete) {
         console.log(chalk.green('All planning artifacts complete!'));
     }
+    if (nextStep) {
+        console.log(`Next: ${nextStep.command}`);
+    }
 }
 //# sourceMappingURL=status.js.map