@fission-ai/openspec 1.13.0 → 1.13.1

package/dist/commands/workflow/instructions.js

@@ -9,9 +9,10 @@ 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 { 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.`,
@@ -440,7 +457,7 @@ 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({
+    const warnings = await collectApplyWarnings({
         state,
         schema,
         changeDir,
@@ -599,13 +616,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.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

package/dist/core/archive.js

@@ -8,11 +8,12 @@ import { VALIDATION_MESSAGES } from './validation/constants.js';
 import chalk from 'chalk';
 import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from './root-selection.js';
 import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, retireSpec, finalizeRetiredSpec, } from './specs-apply.js';
-import { discoverSpecFiles, hasAnyFileUnder } from '../utils/spec-discovery.js';
+import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../utils/spec-discovery.js';
 import { METADATA_FILENAME, readRetireCapabilitiesMarker, readSkipSpecsMarker } from '../utils/change-metadata.js';
 import { confirmPrompt, isNonInteractivePromptError } from '../utils/interactive.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { folderStyleNameProblem } from './id.js';
+import { describeNestedChange, findNestedChangesIn, } from '../utils/nested-change.js';
 function isMissingPathError(error) {
     return (typeof error === 'object' &&
         error !== null &&
@@ -949,6 +950,14 @@ export class ArchiveCommand {
                 ? `Change '${changeName}' not found. Available changes: ${available.join(', ')}`
                 : `Change '${changeName}' not found. No active changes exist in this root.`);
         }
+        // Archiving a namespace folder moves an active, unfinished change into the
+        // archive under a name nobody will look for, and never applies its deltas.
+        // That is silent data loss, so it is refused outright rather than warned
+        // about (#1846).
+        const nested = await findNestedChangesIn(changesDir, changeName);
+        if (nested) {
+            throw new ArchiveBlockedError('archive_change_is_namespace_folder', `Cannot archive '${changeName}': ${describeNestedChange(nested)}`, `Rename openspec/changes/${nested.nested[0]}/ to a flat change directory, then archive it.`);
+        }
         const skipValidation = options.validate === false || options.noValidate === true;
         // Validate specs and change before archiving
         if (!skipValidation) {
@@ -993,6 +1002,13 @@ export class ArchiveCommand {
             // folder, so only a regular file counts.
             const rootSpecStat = await fs.stat(path.join(changeSpecsDir, 'spec.md')).catch(() => null);
             let hasDeltaSpecs = rootSpecStat?.isFile() === true;
+            // Likewise for delta sections in any other file the merge path does not
+            // read (specs/<capability>.md, a note beside spec.md): without this the
+            // zero-delta leniency below archives the change as done with nothing
+            // merged, although validate rejects it.
+            if (!hasDeltaSpecs) {
+                hasDeltaSpecs = (await findUnreadDeltaFiles(changeSpecsDir)).length > 0;
+            }
             // A change that declares skip_specs must not carry any file under
             // specs/ — validate reports that as a conflict, so archive has to run
             // the same check instead of skipping validation because the files

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

@@ -10,4 +10,18 @@ export declare function loadSchema(filePath: string): SchemaYaml;
  * Parses and validates an artifact schema from YAML content.
  */
 export declare function parseSchema(yamlContent: string): SchemaYaml;
+/**
+ * Describes an `apply.tracks` value that is not exactly equal to any artifact's
+ * `generates` value, or returns undefined when there is nothing to report.
+ *
+ * The tracked-tasks lookups select the artifact whose `generates` string equals
+ * `tracks`, so this is a progress-discovery problem, not a claim that nothing
+ * produces the file: a glob `generates: tasks/*.md` really does generate
+ * `tracks: tasks/main.md`, yet the strings differ, so the lookup still misses.
+ * Either way apply keeps working (it reads the path directly), but `openspec
+ * list` and `openspec status` fall back to counting the top-level `tasks.md`,
+ * and apply's remedy cannot name an artifact to build. A typo such as
+ * `task.md` is the other usual cause.
+ */
+export declare function findApplyTracksWarning(schema: SchemaYaml): string | undefined;
 //# sourceMappingURL=schema.d.ts.map

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

@@ -30,6 +30,8 @@ export function parseSchema(yamlContent) {
     validateNoDuplicateIds(schema.artifacts);
     // Check that all requires references are valid
     validateRequiresReferences(schema.artifacts);
+    // Check that the apply phase names artifacts this schema declares
+    validateApplyReferences(schema);
     // Check for cycles
     validateNoCycles(schema.artifacts);
     return schema;
@@ -59,6 +61,56 @@ function validateRequiresReferences(artifacts) {
         }
     }
 }
+/**
+ * Validates that every `apply.requires` id is an artifact the schema declares.
+ *
+ * Apply skips an id that no artifact declares, so a typo silently dropped that
+ * artifact from the apply gate. An unknown artifact `requires` is already a
+ * load error, and this is the same kind of reference.
+ *
+ * `apply.tracks` is deliberately not checked here. It is a path, not an id:
+ * apply reads it as written, so a schema whose `tracks` value does not exactly
+ * match any `generates` value (a hand-written `TODO.md`, or `tasks/main.md`
+ * under a glob `generates: tasks/*.md` that really does produce it) works
+ * today, and failing the load would break every command on it.
+ * `openspec schema validate` reports that case as a warning instead
+ * (see `findApplyTracksWarning`).
+ */
+function validateApplyReferences(schema) {
+    const apply = schema.apply;
+    if (!apply)
+        return;
+    const validIds = schema.artifacts.map(a => a.id);
+    for (const req of apply.requires) {
+        if (!validIds.includes(req)) {
+            throw new SchemaValidationError(`Invalid apply.requires reference: '${req}' does not exist (artifacts: ${validIds.join(', ')})`);
+        }
+    }
+}
+/**
+ * Describes an `apply.tracks` value that is not exactly equal to any artifact's
+ * `generates` value, or returns undefined when there is nothing to report.
+ *
+ * The tracked-tasks lookups select the artifact whose `generates` string equals
+ * `tracks`, so this is a progress-discovery problem, not a claim that nothing
+ * produces the file: a glob `generates: tasks/*.md` really does generate
+ * `tracks: tasks/main.md`, yet the strings differ, so the lookup still misses.
+ * Either way apply keeps working (it reads the path directly), but `openspec
+ * list` and `openspec status` fall back to counting the top-level `tasks.md`,
+ * and apply's remedy cannot name an artifact to build. A typo such as
+ * `task.md` is the other usual cause.
+ */
+export function findApplyTracksWarning(schema) {
+    const tracks = schema.apply?.tracks;
+    if (tracks == null || schema.artifacts.some(a => a.generates === tracks))
+        return undefined;
+    return (`apply.tracks '${tracks}' does not exactly match any artifact's generates value ` +
+        `(generates: ${schema.artifacts.map(a => a.generates).join(', ')}), ` +
+        `so OpenSpec cannot tell which artifact's progress it tracks. ` +
+        `Apply still reads that file as written, but list and status count tasks.md instead. ` +
+        `Make apply.tracks exactly equal one of those generates values, ` +
+        `or confirm that file is maintained outside the artifact graph.`);
+}
 /**
  * Validates that there are no cyclic dependencies.
  * Uses DFS to detect cycles and reports the full cycle path.

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

@@ -18,6 +18,9 @@ function relativePathSchema(fieldName) {
     });
 }
 // Artifact definition schema
+// Upper bound on artifacts in one schema. Keeps `validateNoCycles`' recursive
+// DFS well inside the stack limit for any accepted input.
+const MAX_ARTIFACTS = 1000;
 export const ArtifactSchema = z.object({
     id: z.string().min(1, { error: 'Artifact ID is required' }),
     generates: relativePathSchema('generates field'),
@@ -40,7 +43,15 @@ export const SchemaYamlSchema = z.object({
     name: z.string().min(1, { error: 'Schema name is required' }),
     version: z.number().int().positive({ error: 'Version must be a positive integer' }),
     description: z.string().optional(),
-    artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+    artifacts: z
+        .array(ArtifactSchema)
+        .min(1, { error: 'At least one artifact required' })
+        // Bounded so a hostile schema cannot drive the cycle-detection DFS past the
+        // V8 stack limit and crash with an uncaught RangeError instead of a
+        // validation error.
+        .max(MAX_ARTIFACTS, {
+        error: `A schema may declare at most ${MAX_ARTIFACTS} artifacts`,
+    }),
     // Optional apply phase configuration (for schema-aware apply instructions)
     apply: ApplyPhaseSchema.optional(),
 });

package/dist/core/change-status-policy.d.ts

@@ -33,5 +33,19 @@ export interface ActionContextInput {
 }
 export declare function summarizePlanningHome(planningHome: PlanningHome | undefined): PlanningHomeSummary | undefined;
 export declare function buildActionContext(input: ActionContextInput): ActionContext;
+/**
+ * The one next action for a change, in both the forms the CLI needs.
+ *
+ * `sentence` is what the JSON `nextSteps` contract publishes; `command` is the
+ * bare command the text surface prints. Both are built here so the two
+ * surfaces can never name a different next step.
+ */
+export interface ChangeNextStep {
+    /** Ready-to-run command, including any `--store` flag. */
+    command: string;
+    /** Sentence form carried by the JSON `nextSteps` array. */
+    sentence: string;
+}
+export declare function resolveNextStep(input: ChangeNextStepsInput): ChangeNextStep | undefined;
 export declare function buildNextSteps(input: ChangeNextStepsInput): string[];
 //# sourceMappingURL=change-status-policy.d.ts.map

package/dist/core/change-status-policy.js

@@ -20,16 +20,24 @@ export function buildActionContext(input) {
         constraints: ['Repo-local change artifacts and implementation edits are scoped to this project.'],
     };
 }
-export function buildNextSteps(input) {
+export function resolveNextStep(input) {
     const readyArtifact = input.artifactStatuses.find((artifact) => artifact.status === 'ready');
-    const steps = [];
     const storeFlag = input.storeId ? ` --store ${input.storeId}` : '';
     if (readyArtifact) {
-        steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json before writing that artifact.`);
+        const command = `openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json`;
+        return { command, sentence: `Run ${command} before writing that artifact.` };
     }
-    else if (input.allArtifactsComplete) {
-        steps.push(`All planning artifacts are complete. Run openspec instructions apply --change "${input.changeName}"${storeFlag} --json to inspect implementation progress.`);
+    if (input.allArtifactsComplete) {
+        const command = `openspec instructions apply --change "${input.changeName}"${storeFlag} --json`;
+        return {
+            command,
+            sentence: `All planning artifacts are complete. Run ${command} to inspect implementation progress.`,
+        };
     }
-    return steps;
+    return undefined;
+}
+export function buildNextSteps(input) {
+    const step = resolveNextStep(input);
+    return step ? [step.sentence] : [];
 }
 //# sourceMappingURL=change-status-policy.js.map

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

@@ -5,6 +5,7 @@
  */
 import { getInvocationForAdapter, needsInvocationRewrite } from './invocation.js';
 import { transformCommandInvocations } from '../../utils/command-references.js';
+import { assertWorkflowConditionalsResolved } from '../templates/optional-workflow.js';
 /**
  * Generate a single command file using the provided adapter.
  *
@@ -20,6 +21,7 @@ import { transformCommandInvocations } from '../../utils/command-references.js';
  * @returns Generated command with path and file content
  */
 export function generateCommand(content, adapter) {
+    assertWorkflowConditionalsResolved(content.body, `Command '${content.id}' was generated without resolving its optional-workflow blocks`);
     const invocation = getInvocationForAdapter(adapter);
     const formatted = needsInvocationRewrite(invocation)
         ? { ...content, body: transformCommandInvocations(content.body, invocation) }

package/dist/core/completion-tip.js

@@ -18,8 +18,8 @@
  *   non-TTY runs, which are deferred rather than consumed (see `silent`)
  */
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { getGlobalConfigPath } from './global-config.js';
+import { writeFileAtomically } from './file-state.js';
 import { isCiEnvironment } from '../utils/ci.js';
 import { detectShell } from '../utils/shell-detection.js';
 import { CompletionFactory } from './completions/factory.js';
@@ -94,13 +94,13 @@ function readRawConfig() {
  * write down to this one key, and the rename keeps a reader from ever seeing a
  * half-written config.
  */
-function markTipSeen() {
+async function markTipSeen() {
     const configPath = getGlobalConfigPath();
     const current = readRawConfig() ?? {};
-    const tempPath = `${configPath}.${process.pid}.tmp`;
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(tempPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n', 'utf-8');
-    fs.renameSync(tempPath, configPath);
+    // The shared atomic writer: randomized temp name, owner-only mode, temp file
+    // removed on failure. A predictable `<config>.<pid>.tmp` at the default mode
+    // is both guessable and world-readable once renamed over the config.
+    await writeFileAtomically(configPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n');
 }
 /**
  * Print the completion tip once, the first time the CLI runs.
@@ -121,7 +121,7 @@ export async function maybeShowCompletionTip(options = {}) {
         const decision = await decideTip();
         // Record before printing: if the flag cannot be persisted, staying quiet
         // beats reprinting the tip on every future run.
-        markTipSeen();
+        await markTipSeen();
         if (decision === 'show') {
             console.error(`\n${COMPLETION_TIP_MESSAGE}`);
         }

package/dist/core/completions/installers/bash-installer.js

@@ -2,6 +2,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { FileSystemUtils } from '../../../utils/file-system.js';
+import { shellSingleQuote } from './shell-quote.js';
 /**
  * Installer for Bash completion scripts.
  * Supports bash-completion package and standalone installations.
@@ -105,10 +106,11 @@ export class BashInstaller {
      * @returns Configuration content
      */
     generateBashrcConfig(completionsDir) {
+        const quotedDir = shellSingleQuote(completionsDir);
         return [
             '# OpenSpec shell completions configuration',
-            `if [ -d "${completionsDir}" ]; then`,
-            `  for f in "${completionsDir}"/*; do`,
+            `if [ -d ${quotedDir} ]; then`,
+            `  for f in ${quotedDir}/*; do`,
             '    [ -f "$f" ] && . "$f"',
             '  done',
             'fi',
@@ -177,9 +179,11 @@ export class BashInstaller {
             }
             // Remove lines between markers (inclusive)
             lines.splice(startIndex, endIndex - startIndex + 1);
-            // Remove trailing empty lines
-            while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
-                lines.pop();
+            // Install puts the block at the top of the file followed by one blank
+            // separator line; drop that line too so the file reads as it did before.
+            // Everything else, including the file's final newline, is left as is.
+            if (startIndex === 0 && lines.length > 0 && lines[0].trim() === '') {
+                lines.shift();
             }
             // Write back
             await fs.writeFile(bashrcPath, lines.join('\n'), 'utf-8');
@@ -281,14 +285,18 @@ export class BashInstaller {
      */
     generateInstructions(installedPath) {
         const completionsDir = path.dirname(installedPath);
+        // Quoted exactly like the auto-configured block: these lines are printed
+        // for the user to paste into their own rc file, so an expansion left in
+        // them runs on every future shell start.
+        const quotedDir = shellSingleQuote(completionsDir);
         return [
             'Completion script installed successfully.',
             '',
             'To enable completions, add the following to your ~/.bashrc file:',
             '',
             `  # Source OpenSpec completions`,
-            `  if [ -d "${completionsDir}" ]; then`,
-            `    for f in "${completionsDir}"/*; do`,
+            `  if [ -d ${quotedDir} ]; then`,
+            `    for f in ${quotedDir}/*; do`,
             '      [ -f "$f" ] && . "$f"',
             '    done',
             '  fi',