@fission-ai/openspec 1.12.0 → 1.13.1

package/dist/commands/workflow/instructions.js

@@ -8,13 +8,16 @@ 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 { 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';
 import { parseTaskLines } from '../../utils/task-progress.js';
+import { METADATA_FILENAME } from '../../utils/change-metadata.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
@@ -93,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
@@ -118,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();
     }
@@ -140,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();
@@ -164,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>');
@@ -178,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
@@ -230,6 +242,106 @@ 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.
+ *
+ * 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.
+ */
+async 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 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 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
+    // 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 [
+        ...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.`,
+    ];
+}
 /**
  * Generates apply instructions for implementing tasks from a change.
  * Schema-aware: reads apply phase configuration from schema to determine
@@ -267,6 +379,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 +416,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 +457,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 = await collectApplyWarnings({
+        state,
+        schema,
+        changeDir,
+        changeName,
+        skippedArtifacts: context.skippedArtifacts,
+    });
     return {
         changeName,
         changeDir,
@@ -334,6 +473,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 +516,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 +529,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)
@@ -464,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.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/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.